如何在Ubuntu上使用Swagger进行API版本管理

在 Ubuntu 上使用 Swagger 进行 API 版本管理

一 方案总览

• 采用 OpenAPI 规范编写文档，在 info.version 标注文档版本，在 paths 中使用 /v1、/v2 前缀区分接口版本，保持同一服务内多版本共存与演进。
• 在 Swagger UI 中为每个版本提供独立入口（如 /api-docs/v1、/api-docs/v2），便于并行查看与测试。
• 将规范文件纳入 Git 管理，并在 CI/CD 中自动校验、生成客户端/服务端代码与部署文档，确保与后端实现一致。

二 基于 Node.js Express 的实现步骤

• 安装依赖
  • 更新索引并安装 Node.js/npm（如未安装）：sudo apt update && sudo apt install -y nodejs npm
  • 初始化项目并安装中间件：
    • npm init -y
    • npm i express swagger-ui-express swagger-jsdoc yamljs
• 目录结构
  • ├── app.js
  • ├── swagger
  • │ ├── v1.yaml
  • │ └── v2.yaml
  • └── routes ├── v1.js └── v2.js
• 编写规范示例（swagger/v1.yaml）
  • openapi: 3.0.0
  • info:
    • title: 示例 API
    • version: 1.0.0
  • servers:
    • url: /api/v1
  • paths: /hello: get: summary: 返回 v1 问候 responses: ‘200’: description: OK content: text/plain: schema: type: string
• 配置 Swagger UI 多版本入口（app.js）
  • const express = require(‘express’); const swaggerUi = require(‘swagger-ui-express’); const YAML = require(‘yamljs’); const app = express(); const PORT = process.env.PORT || 3000; const specV1 = YAML.load(‘./swagger/v1.yaml’); const specV2 = YAML.load(‘./swagger/v2.yaml’); app.use(‘/api/v1’, require(‘./routes/v1’)); app.use(‘/api/v2’, require(‘./routes/v2’)); app.use(‘/api-docs/v1’, swaggerUi.serveFiles(specV1, {}), swaggerUi.setup(specV1)); app.use(‘/api-docs/v2’, swaggerUi.serveFiles(specV2, {}), swaggerUi.setup(specV2)); app.listen(PORT, () => console.log(Server on :${PORT}));
• 运行与验证
  • node app.js
  • 访问文档：
    • http://localhost:3000/api-docs/v1
    • http://localhost:3000/api-docs/v2
• 演进到 v2 时
  • 新增 swagger/v2.yaml（info.version 与 servers.url 更新为 /api/v2），补充差异路径/模型。
  • 新增 routes/v2.js 实现新接口。
  • 在 app.js 增加 v2 的 UI 入口并重启服务。

三 其他常见技术栈要点

• .NET 6+ 与 Swashbuckle
  • 配置多文档：builder.Services.AddSwaggerGen(c => { c.SwaggerDoc(“v1”, new OpenApiInfo { Version = “v1”, Title = “API” }); c.SwaggerDoc(“v2”, new OpenApiInfo { Version = “v2”, Title = “API” }); });
  • UI 多入口：app.UseSwaggerUI(c => { c.SwaggerEndpoint(“/swagger/v1/swagger.json”, “API v1”); c.SwaggerEndpoint(“/swagger/v2/swagger.json”, “API v2”); });
  • 控制器版本：使用 [ApiVersion(“1.0”)]、[ApiVersion(“2.0”)] 或路由模板 [Route(“v{version:apiVersion}/[controller]”)]。
• Spring Boot 与 Springfox/Springdoc
  • 通过 Docket 分组按路径选择（如 /api/v1/ 与 /api/v2/），为每组生成独立文档；或在 application.properties 中按需启用/禁用文档与选择版本策略。

四 版本策略与运维实践

• 版本策略
  • 优先采用 URL 路径版本（如 /api/v1/…），清晰直观；必要时可用 请求头（如 X-API-Version）进行版本协商。
  • 文档内使用 语义化版本（如 info.version: 2.1.0），与代码分支/发布标签对齐，便于回溯。
• 自动化与协作
  • 将 openapi.yaml/json 纳入 Git；在 CI/CD 中运行规范校验与生成任务（如使用 OpenAPI Generator 生成客户端 SDK、Mock、服务器桩），并自动部署到文档站点或静态托管。
• 安全与可用性
  • 在 Nginx/Apache 反向代理启用 HTTPS；对 /swagger-ui/、/api-docs/ 等路径配置 认证/授权；生产环境可按需禁用或限制访问。