Ubuntu 上 Swagger 升级指南
先确认你的 Swagger 组件与安装方式
- 常见组件包括：Swagger UI（展示文档的静态页面）、Swagger Editor（在线编辑 OpenAPI/Swagger 文件）、Swagger Codegen（代码生成器），以及在 Spring Boot 项目中常集成的 SpringFox（Swagger 2） 或 SpringDoc（OpenAPI 3）。
- 常见安装方式包括：npm/yarn 全局或本地安装、下载静态文件部署、Docker 镜像运行、以及 Java JAR 方式使用 Codegen。不同方式对应的升级路径不同，先确认你当前使用的是哪一种，再按下文对应步骤执行。
按安装方式的升级步骤
- npm/yarn 本地或全局安装
- 升级 Swagger UI：执行 npm update swagger-ui-dist 或 yarn upgrade swagger-ui-dist。
- 升级 Swagger Editor：执行 npm update swagger-editor 或 yarn upgrade swagger-editor。
- 升级 Swagger Codegen CLI：执行 npm update @swagger-api/swagger-codegen-cli 或 yarn upgrade @swagger-api/swagger-codegen-cli。
- 如需指定版本：在安装命令后加 @版本号（例如：npm install swagger-ui-dist@latest）。升级完成后重启应用并回归测试。
- Node.js 中间件方式（如 swagger-ui-express）
- 全局升级：执行 sudo npm update -g swagger-ui-express；如需指定版本：sudo npm install -g swagger-ui-express@版本号。
- 项目中本地升级：进入项目目录执行 npm install swagger-ui-express@版本号，然后重新启动服务。
- Docker 方式
- 直接在 Dockerfile 中将镜像标签更新为最新版本（如 swaggerapi/swagger-ui、swaggerapi/swagger-editor），随后执行 docker build -t 你的镜像名:新版本 . 并 docker run 或滚动更新部署。
- 手动下载静态文件方式
- 前往 Swagger UI GitHub Releases 下载最新 vX.Y.Z.zip，解压后将新的静态资源替换项目中旧版本目录，并更新 HTML 中对 JS/CSS 的引用路径；如接入了反向代理（如 Nginx），同步检查代理配置是否仍然正确。
- Java 方式（Swagger Codegen CLI）
- 前往 Maven Central 下载最新的 swagger-codegen-cli-版本号.jar，替换项目中的旧 JAR；更新脚本中 -jar 路径后执行，验证生成代码是否成功。
从 Swagger 2 迁移到 OpenAPI 3 的兼容性处理（如你使用 Spring Boot）
- 若项目仍基于 SpringFox（Swagger 2），建议迁移到 SpringDoc（OpenAPI 3） 以获得持续维护与更好兼容性。
- 基本步骤：
- 移除 SpringFox 相关依赖，新增 SpringDoc 依赖（如：springdoc-openapi-ui 最新稳定版）。
- 将注解从 io.swagger.annotations 迁移到 io.swagger.v3.oas.annotations。
- 调整配置与访问路径：Spring Boot 2.x/3.x 使用 SpringDoc 后，常见 UI 路径为 /swagger-ui.html 或 /swagger-ui/（版本不同可能略有差异）；如部署在代理或网关后，确认 Nginx/Ingress 对静态资源和路由的转发配置正确。
回滚与验证清单
- 回滚预案：保留上一版的前端静态文件或 Docker 镜像/Node 依赖的 package-lock.json（或 yarn.lock），升级异常可快速回退；Codegen 保留旧版 JAR。
- 升级后验证：访问 /swagger-ui.html 或 /api-docs 确认页面与接口加载正常；抽样执行关键接口的 Try it out；若使用 Nginx/反向代理，检查静态资源与 API 前缀转发；检查 CORS 与安全策略（生产环境可按需限制访问）。
