如何编写ubuntu swagger API文档 - 问答

在Ubuntu上编写Swagger API文档的步骤

1. 准备基础环境

在Ubuntu系统上，首先需要安装Node.js和npm（Node.js包管理器），这是使用Swagger Editor、Swagger UI等工具的前提。打开终端，执行以下命令：

sudo apt update
sudo apt install -y nodejs npm

安装完成后，可通过nodejs -v和npm -v验证安装是否成功。

2. 安装Swagger核心工具

2.1 安装Swagger Editor（可视化编写规范）

Swagger Editor是Swagger生态中的在线/本地编辑工具，支持YAML/JSON格式的OpenAPI规范编写。通过npm全局安装：

sudo npm install -g swagger-editor-cli

安装完成后，启动本地编辑器实例：

swagger-editor-cli start

这会在默认浏览器中打开Swagger Editor（通常为http://localhost:8080），可直接在线编写或导入现有规范文件。

2.2 安装Swagger UI（可视化展示文档）

Swagger UI用于将OpenAPI规范转换为交互式网页文档，方便测试接口。若项目基于Node.js，可通过npm安装：

npm install -g swagger-ui-express

后续需结合Express框架集成到项目中（见步骤3）。

3. 编写OpenAPI规范文件

OpenAPI规范（OAS）是Swagger文档的基础，定义了API的端点、参数、响应、认证等信息。可通过以下两种方式创建：

3.1 使用Swagger Editor编写

打开Swagger Editor后，在左侧编辑区输入YAML格式的规范（示例如下），右侧会实时预览文档效果。完成后点击“Save”保存为swagger.yaml或swagger.json文件。

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
  description: A simple API for demonstration
paths:
  /users:
    get:
      summary: Get all 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
        name:
          type: string

3.2 手动创建文件

使用文本编辑器（如vim、nano）直接创建YAML文件，内容参考上述示例。保存至项目目录（如./docs/swagger.yaml）。

4. 集成Swagger UI到项目（可选，适用于Web应用）

若项目是基于Node.js的Web应用（如Express），可将Swagger UI集成到应用中，实现文档与应用的联动。示例如下：

4.1 安装依赖

npm install swagger-ui-express yamljs

4.2 编写集成代码

在Express应用的主文件（如app.js）中添加以下代码：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();
// 读取OpenAPI规范文件
const swaggerDocument = YAML.load('./docs/swagger.yaml');
// 集成Swagger UI到/api-docs路径
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

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

4.3 启动应用并访问文档

node app.js

打开浏览器访问http://localhost:3000/api-docs，即可看到交互式的Swagger文档，支持“Try it out”功能测试接口。

5. 自动化生成文档（可选，适用于代码优先的场景）

若已有后端代码（如Go、Java、Spring Boot），可使用工具从代码注释或注解自动生成OpenAPI规范，减少手动编写工作量。

5.1 Go语言（使用swag工具）

安装swag：

go install github.com/swaggo/swag/cmd/swag@latest

初始化swag：在项目根目录运行，生成docs目录及docs.go文件：
```
swag init
```

添加注释：在Controller文件中添加Swagger注释（示例如下）：

// @Summary Get user by ID
// @Description Retrieve a user by their ID
// @Tags Users
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func GetUserByID(c *gin.Context) {
    // 业务逻辑
}

重新生成文档：修改代码后，再次运行swag init，docs目录下的swagger.yaml会自动更新。

5.2 Java/Spring Boot（使用Springfox）

添加依赖：在pom.xml中添加Springfox依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置Swagger：创建配置类，启用Swagger并指定扫描包路径：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API")
                .description("API Documentation")
                .version("1.0")
                .build();
    }
}

添加注解：在Controller中使用Swagger注解（示例如下）：

@Api(tags = "User Management")
@RestController
@RequestMapping("/users")
public class UserController {
    @ApiOperation(value = "Get user by ID", notes = "Returns a single user")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable int id) {
        // 业务逻辑
        return ResponseEntity.ok(new User(id, "John Doe"));
    }
}

访问文档：启动Spring Boot应用，访问http://localhost:8080/swagger-ui.html即可查看文档。

6. 最佳实践建议

遵循OpenAPI规范：使用YAML格式（更易读），遵循OAS 3.0标准，确保文档结构清晰。
模块化管理：按功能模块划分API（如/users、/products），使用tags分类，提高可维护性。
版本控制：在info.version中指定API版本（如1.0.0），便于迭代管理。
参数验证：明确参数的type、required、format（如int64、string），避免歧义。
自动化集成：将Swagger文档生成步骤集成到CI/CD流程（如Maven/Gradle插件、npm脚本），确保文档与代码同步。

0 赞

0 踩