ubuntu swagger如何更新换代

Ubuntu 上 Swagger 更新换代指南

一 先确认你正在使用的组件

• 常见组件包括：Swagger UI（展示文档的静态页面）、Swagger Editor（在线编辑 OpenAPI/Swagger 规范）、Swagger Codegen（从规范生成客户端/服务端代码）、以及后端框架集成如 SpringFox（Swagger 2） 或 SpringDoc（OpenAPI 3）。不同组件的更新方式不同，先明确你用的是哪一种，再按下文对应步骤升级。

二 按安装方式的升级步骤

• 使用 npm/yarn 全局安装
  • 升级 Swagger UI：执行 npm update -g swagger-ui-dist 或 yarn global upgrade swagger-ui-dist
  • 升级 Swagger Editor：执行 npm update -g swagger-editor 或 yarn global upgrade swagger-editor
  • 升级 Swagger Codegen：执行 npm update -g @swagger-api/swagger-codegen-cli 或 yarn global upgrade @swagger-api/swagger-codegen-cli
  • 如需固定版本：npm install -g swagger-ui-dist@<version>（将 替换为目标版本号）
• 使用 Docker 运行
  • 拉取最新镜像：docker pull swaggerapi/swagger-ui:latest、docker pull swaggerapi/swagger-editor:latest
  • 滚动更新：先 docker stop <container_id>，再 docker rm <container_id>，最后用最新镜像重新 docker run -d -p 8080:8080 swaggerapi/swagger-ui:latest（UI 默认 8080 端口，Editor 常用 8080，可按需映射）
• 使用系统包管理器 apt
  • 先 sudo apt update，再 sudo apt install --only-upgrade swagger-ui-express（如系统仓库提供该包）。注意：apt 源版本往往滞后，如需最新特性建议改用 npm 或 Docker 方式。

三 从 Swagger 2 升级到 OpenAPI 3（兼容性与迁移）

• 若你的项目仍基于 Swagger 2 / SpringFox，建议迁移到 OpenAPI 3 / SpringDoc，以获得持续维护与更好生态支持：
  • 移除 SpringFox 依赖，添加 SpringDoc 依赖（Maven）：

    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>2.0.2</version>
    </dependency>
    

  • 注解迁移：将 io.swagger.annotations 替换为 io.swagger.v3.oas.annotations
  • 访问路径：SpringDoc 默认 UI 路径为 /swagger-ui.html（与 SpringFox 的 /swagger-ui.html 位置保持一致，便于平滑切换）
  • 如存在多分组、代理（Nginx）等场景，需同步调整配置与网络策略。

四 验证与回滚建议

• 验证：升级后重启服务或容器，访问 Swagger UI（如 http://localhost:8080 或 /swagger-ui.html），确认能正确加载你的 swagger.yaml/json 规范并能正常调试接口。
• 回滚：保留旧版本安装包或镜像标签；出现问题时可快速切回上一版本（如 npm install -g swagger-ui-dist@<old_version>，或 docker run ... swaggerapi/swagger-ui:<old_tag>）。
• 注意：升级前务必备份项目配置与规范文件；如使用 Docker，更新镜像后需重建并部署容器；如仍在用 Swagger 2，优先考虑迁移到 OpenAPI 3 以避免后续兼容与安全风险。