centos swagger兼容性检查

CentOS 上 Swagger 兼容性检查清单

一 环境基线核对

• 运行环境：确认 CentOS 版本、JDK 版本（如 JDK 8/11/17）、应用容器（如 Tomcat 9+/Jakarta EE 9+）、反向代理（如 Nginx）与端口开放情况。
• 依赖框架：明确 Spring Boot 版本，区分 Swagger 2（SpringFox） 与 OpenAPI 3（SpringDoc） 两套生态，避免混用。
• 访问链路：浏览器 → Nginx/Apache → 应用 → /v3/api-docs 或 /swagger-ui/，逐跳核对连通性与返回内容类型。

二 版本与依赖兼容性检查

• 生态选择：优先使用 SpringDoc（OpenAPI 3） 替代已停止维护的 SpringFox（Swagger 2）；若仍在用 SpringFox，需确认与当前 Spring Boot 版本的兼容矩阵。
• 依赖冲突：使用 Maven/Gradle 的“依赖树”排查冲突（如多版本 Guava、不同 jakarta.servlet 包）；必要时锁定版本或排除旧依赖。
• 注解与模型：SpringDoc 常用 @Tag、@Operation、@Schema；确保包扫描覆盖控制器与模型包，避免文档为空。
• 版本示例：如采用 SpringDoc，可固定稳定版本（例如 1.6.x 系列），并在升级时回归核心接口用例。

三 配置与网络连通性检查

• Spring Security 放行：为 /v3/api-docs、/swagger-ui/ 及静态资源路径放行，避免 404/403。
• Spring Boot 2.6+ 适配：如启用 PathPattern 或新路径匹配策略，需相应调整 Swagger 配置与资源映射。
• 资源与权限：检查 target/classes/static 或 Nginx 静态目录的读写权限，避免因权限导致 Swagger UI 空白或 404。
• 端口与防火墙：核对应用端口（如 8080/8443）、firewalld/SELinux 策略与云安全组规则，确保外部可达。
• Nginx 代理头与前缀：正确设置 X-Forwarded-For/Proto/Prefix，当 UI 与后端分离部署时尤其关键，避免 JSON 加载失败。

四 快速验证与回归测试

• 文档可达性：访问 /v3/api-docs（OpenAPI 3）或 /v2/api-docs（Swagger 2），确认返回 200 且 Content-Type: application/json。
• UI 可用性：访问 /swagger-ui/ 或 /swagger-ui.html，检查接口列表、模型、Try-It-Out 是否正常渲染与调用。
• 接口回归：对核心业务接口执行“文档驱动”的冒烟测试，核对 请求/响应 Schema、状态码与错误码说明是否一致。
• 自动化与覆盖：在 CI 中加入“文档生成 + 静态扫描（如 schema 校验）”与“关键路径接口回归”，并保留失败快照便于回溯。

五 常见症状与修复要点

• 页面空白或 404/503：检查 静态资源映射、Security 放行、应用是否真正暴露文档端点与端口连通性。
• 文档未更新：确认构建与发布流程包含最新的 OpenAPI/Swagger JSON，必要时触发文档刷新或重启应用。
• 注解不生效/无内容：核对 @Tag/@Operation/@Schema 使用、包扫描路径，排除旧版 SpringFox 依赖残留。
• 依赖冲突导致启动失败：用依赖树定位冲突（如 Guava、jakarta.servlet），统一版本或排除旧依赖。
• 中文或路径显示异常：若使用独立 Swagger UI 静态包，注意版本差异与 index.html 中 URL 指向；Nginx 反向代理需正确设置 X-Forwarded-Prefix。