如何在Ubuntu中更新Swagger

在 Ubuntu 中更新 Swagger 的实用步骤

先确认你正在使用的组件

Swagger UI：展示 OpenAPI/Swagger 文档的静态页面与前端资源。
Swagger Editor：在线编辑 OpenAPI/Swagger 规范的编辑器。
Swagger Codegen / OpenAPI Generator：根据规范生成客户端或服务端代码的工具。
Spring Boot 集成：常见为 SpringFox（Swagger 2） 或 SpringDoc（OpenAPI 3）。不同组件的更新方式不同，请按下方对应方案执行。

按安装方式的更新方法

使用 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：执行 npm update @swagger-api/swagger-codegen-cli 或 yarn upgrade @swagger-api/swagger-codegen-cli。
- 本地项目建议进入项目目录执行，确保 package.json 与 package-lock.json 同步更新。
使用 Docker 运行
- 拉取最新镜像：docker pull swaggerapi/swagger-editor:latest、docker pull swaggerapi/swagger-ui:latest。
- 更新步骤：先 docker stop <container_id> 与 docker rm <container_id>，再拉取新镜像并 docker run -d -p <host_port>:8080 重新启动（注意端口映射保持一致）。
使用 发行包手动部署
- 前往 GitHub Releases 下载指定版本的 Swagger Editor/UI 压缩包，解压后用新文件替换旧版本静态资源，保持 index.html 等入口引用路径一致。
使用 Java JAR（Codegen）
- 从 Maven Central 下载最新的 swagger-codegen-cli-.jar，替换旧 JAR 后按原命令执行生成操作。

Spring Boot 项目的更新要点

若当前使用 SpringFox（Swagger 2），建议迁移到 SpringDoc（OpenAPI 3） 以获得持续维护与更好兼容性。
依赖调整（Maven 示例）：移除 SpringFox，新增 springdoc-openapi-ui 依赖，例如：
- org.springdoc
  springdoc-openapi-ui
  2.0.2
注解迁移：将 io.swagger.annotations 替换为 io.swagger.v3.oas.annotations 系列注解。
访问路径：SpringDoc 默认 UI 路径为 /swagger-ui.html（与 SpringFox 的 /swagger-ui.html 位置一致，便于替换）。更新后启动应用并回归测试接口文档与分组配置。

更新后的验证与回滚建议

验证要点
- 访问 Swagger UI 页面，确认 OpenAPI/Swagger 规范能正确加载，接口分组、模型、示例与授权配置正常。
- 若使用 Codegen，用更新后的工具重新生成代码并编译、跑通基础用例。
- 检查浏览器控制台与后端日志，排除资源 404/跨域/解析错误 等问题。
回滚方案
- npm/yarn：使用 npm install @<old_version> 或 yarn add @<old_version> 回退；Docker 使用之前的镜像标签或 docker tag 保留的历史镜像重新运行；手动部署保留旧版本目录以便快速替换。