如何利用Ubuntu Swagger生成API文档_运维文库_资讯中心

发布时间:2026-04-27 10:44:33

阅读量:0

如何在Ubuntu上使用Swagger生成API文档
在Ubuntu系统上，Swagger（现多为OpenAPI规范）可通过Node.js工具链或**编程框架（如Spring Boot）**生成API文档。以下是两种常见场景的具体步骤：

一、基于Node.js环境（适用于纯API服务或轻量级项目）

1. 安装必要工具

首先确保系统已安装Node.js和npm（Node.js包管理器），用于安装Swagger相关工具：

sudo apt update
sudo apt install -y nodejs npm

验证安装：

node -v  # 查看Node.js版本
npm -v   # 查看npm版本

2. 安装Swagger工具

通过npm全局安装Swagger UI Express（用于托管文档）和Swagger-jsdoc（用于从代码注释生成文档）：

sudo npm install -g swagger-ui-express swagger-jsdoc

3. 编写API规范（YAML/JSON格式）

创建swagger.yaml文件（推荐YAML格式，更易读），定义API元数据、路径、参数及响应：

openapi: 3.0.0
info:
  title: Sample API
  description: A simple API for demonstration
  version: 1.0.0
servers:
  - url: http://localhost:3000
    description: Local development server
paths:
  /users:
    get:
      summary: Get all users
      description: Retrieve a list of all registered users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique user ID
        name:
          type: string
          description: User's full name

4. 配置Swagger UI

创建一个简单的Express应用，集成Swagger UI以可视化文档：

// server.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const yaml = require('yamljs');

// 加载Swagger文档
const swaggerDocument = yaml.load('./swagger.yaml');

const app = express();
const PORT = 3000;

// 托管Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
  console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);
});

5. 启动服务并访问文档

启动Express应用：

node server.js

打开浏览器访问http://localhost:3000/api-docs，即可看到交互式的Swagger UI界面，包含API的所有路径、参数及示例。

二、基于Spring Boot框架（适用于Java后端项目）

若项目使用Spring Boot，可通过Swagger注解自动生成文档，步骤如下：

1. 添加Swagger依赖

在pom.xml（Maven）中添加Swagger核心依赖和UI依赖：

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-boot-starterartifactId>
    <version>3.0.0version>
dependency>

2. 配置Swagger扫描范围

创建配置类SwaggerConfig.java，指定扫描的Controller包路径：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 替换为你的Controller包路径
                .paths(PathSelectors.any())
                .build();
    }
}

3. 使用注解丰富文档

在Controller类和方法上添加Swagger注解，描述接口功能、参数及响应：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/api/users")
@Api(tags = "User Management", description = "Operations related to user management")
public class UserController {

    @GetMapping
    @ApiOperation(value = "Get all users", notes = "Retrieve a list of all registered users")
    public List getAllUsers() {
        List users = new ArrayList<>();
        users.add("John Doe");
        users.add("Jane Smith");
        return users;
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "Get user by ID", notes = "Retrieve a user by their unique ID")
    public String getUserById(
            @ApiParam(value = "User ID", required = true, example = "1")
            @PathVariable Long id) {
        return "User " + id;
    }
}

4. 启动应用并访问文档

启动Spring Boot应用，访问http://localhost:8080/swagger-ui/index.html（端口可能因配置不同而变化），即可看到自动生成的API文档，包含接口描述、参数说明及测试界面。

注意事项

规范一致性：确保YAML/JSON格式符合OpenAPI规范（如字段拼写、结构层级）。
注解完整性：使用注解（如@ApiOperation、@ApiParam）详细描述接口，提升文档可读性。
安全性：生产环境中，建议通过认证（如API Key、OAuth2）保护Swagger UI接口，避免未授权访问。

以上步骤覆盖了Ubuntu环境下Swagger生成API文档的主要场景，可根据项目技术栈选择合适的方式。

以上就是关于“如何利用Ubuntu Swagger生成API文档”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！

简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm