Linux环境中Swagger API文档如何版本控制

Linux环境下Swagger API文档版本控制实践

一 版本控制总览

• 使用Git管理规范文件（如swagger.yaml/openapi.yaml），在文件中用openapi: 3.0.0或swagger: '2.0’声明规范版本，每次变更提交并写明变更范围与兼容性；通过分支隔离不同版本的开发与发布（如 feature/v1.1 → main）。
• 在规范层面区分两类版本：
  1. API 版本（业务版本，如 v1、v2），体现在文档的info.version与paths分组；
  2. 规范版本（如 OpenAPI/Swagger 语法版本），体现在文件头的openapi/swagger字段。
• 运行时通过Swagger UI按分组或路径展示不同版本的文档，便于并行维护与回归验证。

二 目录与分支策略

• 推荐的仓库结构（单仓多版或一版一仓均可，示例为单仓多版）：

api-spec/
├── specs/
│   ├── v1/
│   │   ├── openapi.yaml
│   │   └── components.yaml
│   └── v2/
│       ├── openapi.yaml
│       └── components.yaml
├── README.md
└── .gitignore

• 分支策略建议：
  • main：稳定版（如 v1）
  • release/v2：发布候选（RC）与热修复
  • feature/v2.x：新版本功能开发
  • 通过 PR 合并，配合语义化版本标签（如 v1.2.3）与变更说明（CHANGELOG）。

三 规范层面的版本管理

• 在info.version标注业务版本，在paths中使用**/api/v1/、/api/v2/区分路由；必要时用tags**对资源分组，便于 UI 按组展示。
• 示例（openapi.yaml 片段）：

openapi: 3.0.0
info:
  title: 用户服务 API
  version: 2.0.0
paths:
  /api/v1/users:
    get:
      summary: 获取用户列表 v1
      responses:
        '200':
          description: OK
  /api/v2/users:
    get:
      summary: 获取用户列表 v2（含分页）
      responses:
        '200':
          description: OK

• 兼容性策略：尽量避免破坏性变更；必要时通过新增字段/新路径保持向后兼容，旧版文档保留在仓库与 UI 中供存量调用方参考。

四 运行时多版本发布与展示

• Node.js + Express 示例（多文件多版本）：

// swagger-v1.js
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerOptionsV1 = {
  swaggerDefinition: { openapi: '3.0.0', info: { title: 'API', version: '1.0.0' } },
  apis: ['./routes/v1/*.js'],
};
const swaggerDocsV1 = swaggerJsDoc(swaggerOptionsV1);

// swagger-v2.js
const swaggerOptionsV2 = {
  swaggerDefinition: { openapi: '3.0.0', info: { title: 'API', version: '2.0.0' } },
  apis: ['./routes/v2/*.js'],
};
const swaggerDocsV2 = swaggerJsDoc(swaggerOptionsV2);

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const app = express();
app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(swaggerDocsV1));
app.use('/api-docs/v2', swaggerUi.serve, swaggerUi.setup(swaggerDocsV2));
app.listen(3000, () => console.log('Docs: /api-docs/v1  |  /api-docs/v2'));

• Spring Boot 示例（Springfox 3，按组展示多版本）：

@Configuration
public class SwaggerConfig {
  @Bean
  public Docket v1() {
    return new Docket(DocumentationType.OAS_30)
        .groupName("v1")
        .select().apis(RequestHandlerSelectors.basePackage("com.example.controller.v1")).paths(PathSelectors.any()).build()
        .apiInfo(new ApiInfoBuilder().title("API v1").version("1.0").build());
  }
  @Bean
  public Docket v2() {
    return new Docket(DocumentationType.OAS_30)
        .groupName("v2")
        .select().apis(RequestHandlerSelectors.basePackage("com.example.controller.v2")).paths(PathSelectors.any()).build()
        .apiInfo(new ApiInfoBuilder().title("API v2").version("2.0").build());
  }
}
// 访问：/swagger-ui/ 可见 v1、v2 分组

• 访问方式：
  • 路径式：/api-docs/v1、/api-docs/v2（或 Spring Boot 的 /swagger/v1/swagger.json 与 /swagger-ui/ 分组入口）。
  • 如需在 UI 中并列展示多个规范，可为每个版本单独部署一套 Swagger UI 或使用反向代理按路径分发。

五 协作与发布流程

• 本地编辑规范 → 提交到Git并打标签（如 v2.0.0）→ 运行 CI 校验（如 swagger-cli validate）→ 生成客户端/服务端桩代码（如 OpenAPI Generator）→ 部署到开发/预发/生产环境的文档站点（Nginx/容器）→ 变更记录写入 CHANGELOG 并通知调用方。
• 常用命令示例：

# 校验
npx swagger-cli validate specs/v2/openapi.yaml

# 生成 Java 客户端
wget https://repo1.maven.org/maven2/io/swagger/openapi-generator-cli/2.4.21/openapi-generator-cli-2.4.21.jar -O openapi-generator.jar
java -jar openapi-generator-cli-2.4.21.jar generate -i specs/v2/openapi.yaml -g java -o ./gen/v2-client

# 运行 Swagger Editor（本地预览差异）
wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v4.6.0.tar.gz
tar -xvf v4.6.0.tar.gz && cd swagger-editor-4.6.0
npm install && nohup npm start &
# 浏览器打开 http://<server>:8080，通过 File → Open URL 打开 specs/v1/openapi.yaml 与 specs/v2/openapi.yaml 对比

• 可选平台：使用 Apifox、eolink 等 API 管理平台导入规范，利用其版本管理、变更通知、Mock/测试能力提升协作效率。