Ubuntu 上 Swagger 的更新方式取决于你的安装形态。常见有本机 Node.js/npm 安装、Docker 容器运行、以及集成在后端框架（如 Spring Boot）中的 Swagger/OpenAPI 工具链。下面按场景给出可操作的升级步骤与要点。
本机 Node.js 与包管理器安装
- 确认当前包与版本：
- npm：执行命令查看可更新包与当前版本差异：npm outdated | grep swagger
- yarn：执行命令：yarn outdated | grep swagger
- 执行升级（以常用组件为例）：
- Swagger UI：npm update swagger-ui-dist 或 yarn upgrade swagger-ui-dist
- Swagger Editor：npm update swagger-editor 或 yarn upgrade swagger-editor
- Swagger Codegen（OpenAPI Generator CLI）：npm update @swagger-api/swagger-codegen-cli 或 yarn upgrade @swagger-api/swagger-codegen-cli
- 升级后验证：
- 检查版本：npm list swagger-ui-dist、npm list swagger-editor、npm list @swagger-api/swagger-codegen-cli
- 清理与重启：如有缓存或进程占用，执行 npm cache verify，并重启承载服务（如 npm run serve 或 PM2 管理的进程）。
Docker 运行时的更新
- 拉取最新镜像（以官方镜像为例）：
- Swagger Editor：docker pull swaggerapi/swagger-editor:latest
- Swagger UI：docker pull swaggerapi/swagger-ui:latest
- 滚动更新（零停机思路，示例以 UI 为例）：
- 启动新容器：docker run -d --name swagger-ui-new -p 8081:8080 swaggerapi/swagger-ui:latest
- 确认可用后切换流量并清理旧容器：
- 切换 Nginx/负载均衡指向新端口 8081
- 停止旧容器：docker stop swagger-ui-old && docker rm swagger-ui-old
- 若使用 docker-compose，更新镜像后执行：docker-compose pull && docker-compose up -d --force-recreate。
集成在后端框架中的更新
- Spring Boot 项目常见从 SpringFox（Swagger 2） 迁移到 SpringDoc（OpenAPI 3），以适配新生态与修复兼容性问题：
- 移除 SpringFox 依赖，新增 SpringDoc 依赖（Maven 示例）：
- org.springdoc springdoc-openapi-ui 2.0.2
- 注解迁移：将 io.swagger.annotations 替换为 io.swagger.v3.oas.annotations
- 访问路径变化：默认 UI 从 /swagger-ui.html 调整为 /swagger-ui/index.html（版本与配置不同可能略有差异）
- 如仍在用 Swagger 2，建议规划迁移到 OpenAPI 3，以获得更好的维护与兼容性支持。
升级前后注意事项
- 备份与回滚：升级前备份项目配置、静态资源与容器镜像标签；准备好回滚方案（如保留旧版镜像与目录）。
- 兼容性验证：升级后重点回归接口分组、鉴权、模型定义与自定义扩展，确保文档展示与对接客户端正常。
- 安全建议：生产环境可限制文档访问来源、鉴权访问或按需禁用，避免暴露内部接口细节。
