centos swagger如何迁移

CentOS 上 Swagger 迁移实操指南

一、迁移场景与总体策略

• 原地升级：在现有 CentOS 服务器上，把文档方案从 SpringFox/Swagger 2.x 升级到 SpringDoc OpenAPI 3.x，以适配 JDK 17+ / Spring Boot 3.x / Jakarta EE 9+，并顺带完成规范从 OpenAPI 2.0 到 OpenAPI 3.0 的迁移。此路径改动可控，风险较低。
• 平台迁移：把文档从自建服务迁移到 Docker 容器或新的主机，便于环境一致性与回滚；可与原地升级结合执行。
• 规范迁移：无论是否更换运行时，建议将 Swagger 2.0 注解迁移为 OpenAPI 3.0 注解，避免后续维护成本。

二、原地升级步骤 SpringFox 2.x → SpringDoc OpenAPI 3.x

• 环境与依赖
  • 升级到 JDK 17+、Spring Boot 3.x（如需），并确保使用 Jakarta EE 9+ 依赖。
  • 移除 SpringFox 依赖，新增 SpringDoc 依赖（示例）：
    • Maven

      <!-- 移除 -->
      <!-- <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>3.0.0</version>
         </dependency>
         <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>3.0.0</version>
         </dependency> -->
      <!-- 新增 -->
      <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.5.0</version>
      </dependency>
      

    • Gradle

      // implementation "io.springfox:springfox-swagger2:3.0.0"
      // implementation "io.springfox:springfox-swagger-ui:3.0.0"
      implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0"
      

• 代码层注解迁移（核心对照）
  • @Api → @Tag，@ApiOperation → @Operation，@ApiParam → @Parameter，@ApiModel/@ApiModelProperty → @Schema，@ApiIgnore → @Hidden。
  • 示例：

    // 旧
    @Api(tags = "用户管理")
    public class UserController {
      @ApiOperation("创建用户")
      public User create(@ApiParam("用户DTO") @RequestBody UserDTO dto){...}
    }
    
    // 新
    @Tag(name = "用户管理")
    public class UserController {
      @Operation(summary = "创建用户", description = "根据DTO创建用户")
      public User create(@Parameter(description = "用户DTO", required = true) @RequestBody UserDTO dto){...}
    }
    

• 配置与路径
  • SpringDoc 默认提供 /v3/api-docs 与 /swagger-ui.html；可在 application.yml 调整：

    springdoc:
      api-docs:
        enabled: true
        path: /v3/api-docs
      swagger-ui:
        enabled: true
        path: /swagger-ui.html
    

  • 若项目存在安全拦截器/网关，放行上述路径与静态资源。
• 常见问题与排查
  • 出现 javax.servlet 与 jakarta.servlet 冲突：统一为 Jakarta EE 9+ 版本，排除旧依赖。
  • 页面空白或 404：确认依赖已引入、静态资源未被拦截、访问路径正确。
  • 注解不生效：检查包导入是否为 io.swagger.v3.oas.annotations。

三、平台迁移步骤 CentOS 原地 → Docker 或新主机

• Docker 方式（推荐）
  • 安装 Docker（CentOS）：

    sudo yum install -y docker
    sudo systemctl start docker
    sudo systemctl enable docker
    

  • 运行 Swagger Editor 与 Swagger UI（示例）：

    docker run -d -p 8080:8080 swaggerapi/swagger-editor:latest
    docker run -d -p 8081:8080 swaggerapi/swagger-ui:latest
    

  • 更新：停止旧容器 → 拉取新镜像 → 重新运行。
• 手动静态部署（Swagger UI 展示已有 JSON）
  • 将 swagger.json 放到 /var/www/html/swagger/，修改 dist/index.html 中的 url 指向该文件；用 Nginx/Apache 托管静态文件并配置反向代理或 CORS。
• 迁移校验
  • 核对 接口分组、模型定义、响应示例 是否完整；在容器与主机间保持一致的 Nginx 配置与防火墙策略。

四、防火墙与网络可达性

• 开放文档端口（示例为 8080/8081/3000）：

  sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
  sudo firewall-cmd --zone=public --add-port=8081/tcp --permanent
  sudo firewall-cmd --zone=public --add-port=3000/tcp --permanent
  sudo firewall-cmd --reload
  

• 若经由 Nginx/Ingress 暴露，确保路由与 TLS 配置正确。

五、验证与回滚

• 验证清单
  • 访问 /swagger-ui.html 能正常渲染；/v3/api-docs 返回有效 OpenAPI 3.0 JSON。
  • 核心业务接口均包含 summary/description、参数与响应示例、分组与标签。
  • 安全策略生效（生产环境建议鉴权访问）。
• 回滚方案
  • Docker：保留旧容器镜像与挂载卷，出现异常可快速回滚到上一个标签。
  • 原地升级：保留旧依赖与配置，使用开关（如 springdoc.enabled=false）快速切回；必要时回滚代码与依赖版本。