在 Debian 上让 Swagger 文档持续保持最新
一 总体思路
- 将文档与代码同源：用代码注解或规范文件（如 OpenAPI/Swagger）生成文档，随代码变更自动更新。
- 固定展示层版本：将 Swagger UI/Editor 作为静态资源或容器镜像锁定版本，随应用一起发布，避免“跑在旧 UI 上”。
- 纳入版本控制与发布流程：把规范文件纳入 Git，在 CI/CD 中校验、生成并发布，保证环境一致性。
- 多版本并存与路由隔离：为 v1/v2 提供独立的规范与 UI 路径，避免互相覆盖。
二 按运行方式的落地做法
-
Node.js/Express 项目
- 安装与集成：使用 swagger-jsdoc + swagger-ui-express 生成并托管文档。
- 安装：
npm i swagger-jsdoc swagger-ui-express --save
- 示例：
- const swaggerJsdoc = require(‘swagger-jsdoc’); const swaggerUi = require(‘swagger-ui-express’);
- const options = { definition: { openapi: ‘3.0.0’, info: { title: ‘API’, version: ‘1.0.0’ } }, apis: [‘./routes/*.js’] };
- const specs = swaggerJsdoc(options); app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(specs));
- 保持最新：
- 规范随代码变更更新；提交到 Git 后由 CI 运行生成与部署。
- 若使用全局包：
sudo npm update -g swagger-ui-express；更推荐将版本写入 package.json 随应用发布。
- Docker：更新镜像（如
swaggerapi/swagger-ui），重建并滚动发布。
-
Java/Spring Boot 项目
- 集成方式：使用 Springfox（如 springfox-boot-starter:3.0.0）或 SpringDoc OpenAPI（推荐，社区更活跃）。
- 保持最新：
- 升级依赖版本后重新编译打包；应用启动即提供最新的 /v3/api-docs 与 /swagger-ui.html。
- 规范变更体现在代码注解与配置，随服务发布自动生效。
-
PHP 项目
- 生成工具：使用 zircote/swagger-php 注解生成 OpenAPI 规范。
- 保持最新：
- 在代码变更后执行
vendor/bin/openapi --output ./docs/openapi.yaml --path ./src
- 将生成的 openapi.yaml 纳入 Git 并由 CI 部署到静态站点或集成到服务中。
三 版本管理与多版本并存
- 规范文件按版本拆分：如 openapi-v1.yaml / openapi-v2.yaml，各自描述对应版本的 paths/组件。
- UI 按路径隔离：
- app.use(‘/api-docs/v1’, swaggerUi.serve, swaggerUi.setup(require(‘./v1/openapi.json’)));
- app.use(‘/api-docs/v2’, swaggerUi.serve, swaggerUi.setup(require(‘./v2/openapi.json’)));
- 访问方式：
- v1 文档：/api-docs/v1
- v2 文档：/api-docs/v2
- 建议将规范与路由、控制器的版本目录结构保持一致，便于维护与发布。
四 自动化与运维实践
- Git 与分支策略：将 swagger.yaml/openapi.yaml 纳入 Git；按功能分支更新规范，合并到主干后触发发布。
- CI/CD 示例（GitHub Actions）
- 触发：push 到 main
- 步骤：checkout → 安装依赖 → 生成规范（如
openapi-generator/swagger-cli）→ 校验（如 swagger-cli validate）→ 部署到静态托管或拷贝到后端静态目录 → 重启服务或滚动更新容器
- 容器化与静态托管
- 容器：更新 swagger-ui 镜像标签，重建并滚动升级；或把生成的 dist 静态文件挂载到 Nginx。
- 静态：将规范与 UI 静态文件托管到对象存储或 Nginx，路径与后端路由保持一致。
- 安全与变更管控
- 对文档站点启用 Basic Auth/Nginx 访问控制；变更走 PR 审核 与 变更日志，避免误改。
