Linux上Swagger版本升级注意事项

Linux上Swagger版本升级注意事项

一 升级前的兼容性评估

• 明确当前技术栈：区分是 SpringFox（Swagger 2.x） 还是 SpringDoc/Knife4j（OpenAPI 3.x），以及运行的 JDK 与 Spring Boot 版本。
• 关键兼容性矩阵（简版）：
  • JDK 8：优先 SpringFox 2.x；SpringDoc 1.x 可用；SpringDoc 2.x 不支持。
  • JDK 17：SpringFox 2.x 不支持；SpringDoc 1.x 不支持；SpringDoc 2.x 支持。
  • Spring Boot 3.x：需 Jakarta EE 9+，对应 SpringDoc 2.x；SpringFox 2.x 不兼容。
  • 维护状态：SpringFox 已停止维护，存在如 CVE-2021-28170 等风险；建议新项目优先 SpringDoc/Knife4j。
• 若计划从 JDK 8 → JDK 17 或 Spring Boot 2.x → 3.x，通常意味着从 SpringFox → SpringDoc 的迁移，并伴随 javax → jakarta 包名变更。

二 依赖与构建变更

• 从 SpringFox 迁移到 SpringDoc（示例 Maven 变更）：
  • 移除旧依赖：
    • io.springfox:springfox-swagger2
    • io.springfox:springfox-swagger-ui
  • 引入新依赖（按运行环境选择其一）：
    • Spring Web MVC：org.springdoc:springdoc-openapi-starter-webmvc-ui
    • WebFlux：org.springdoc:springdoc-openapi-starter-webflux-ui
    • 可选增强 UI：com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter（Jakarta 场景）
• 依赖冲突治理：
  • 使用 Maven Helper 等工具排查冲突，尤其是 Guava 等多版本并存。
  • 如出现 javax.servlet 与 jakarta.servlet 混用，需统一依赖版本并排除冲突的 javax.servlet-api。
• 配置方式变化：
  • SpringFox 使用 @EnableSwagger2 与 Docket；
  • SpringDoc 多数场景 零配置自动扫描，可通过 application.properties/yaml 或 OpenAPI Bean 自定义。

三 注解与规范迁移

• 常见注解映射（Swagger 2.x → OpenAPI 3.x / SpringDoc）：
  • @Api → @Tag（类级分组说明）
  • @ApiOperation → @Operation（方法级摘要与描述）
  • @ApiParam → @Parameter（参数说明，含 required 等）
  • @ApiResponse → @ApiResponse（响应码与描述）
  • @ApiIgnore → @Hidden（隐藏接口或参数）
  • 复杂参数组合可用 @Parameters 与 @Parameter 配合。
• 模型与字段：
  • 继续使用 @Schema（或保留 @ApiModelProperty 以平滑过渡），确保示例、格式与校验规则完整。
• 规范差异：
  • 从 OpenAPI 2.0 迁移到 OpenAPI 3.0，请求/响应结构、媒体类型与组件定义更灵活，建议按需调整 DTO 示例与响应模型。

四 运行时与运维注意

• 访问路径变化：
  • SpringFox 2.x 常见为 /swagger-ui.html；
  • SpringDoc 默认 /swagger-ui.html 或 /swagger-ui/（以版本为准）。
• 容器与发布：
  • 如使用 Docker，在 Dockerfile 中固定 Swagger UI / Editor / Codegen 的版本号，变更后需 重新构建镜像 与 滚动发布。
• 安全与访问控制：
  • 生产环境建议开启 鉴权/白名单，避免接口被未授权调用；如使用 Knife4j，可利用其 权限控制、接口分组 等增强能力。
• 网络与权限：
  • 在 Linux 环境排查 端口占用、防火墙策略、反向代理配置，确保文档页可访问。
• 验证与回滚：
  • 升级后进行 功能测试、性能测试 与 契约校验；保留可回滚的 稳定版本 与 构建产物，出现问题快速回退。

五 常见陷阱与排查清单

• 混用 SpringFox 与 SpringDoc 导致 Bean 冲突/重复注册。
• Jakarta 与 Java EE 包名混用引发 NoSuchMethodError/ClassNotFoundException。
• JDK 版本不匹配：如 SpringDoc 2.x 要求 JDK 17+。
• 依赖冲突（如 Guava、javax.servlet），需统一版本并排除冲突。
• 配置未生效：SpringDoc 默认自动扫描，若自定义 OpenAPI Bean 需确保被加载。
• 访问 404：检查 context-path、反向代理、路径前缀 与 安全拦截规则。
• 排查建议：开启 DEBUG/TRACE 日志、使用构建工具分析依赖树、在测试环境完整回归核心业务链路。