CentOS 上 Swagger 依赖管理技巧
一 环境与工具选型
- 区分两类依赖来源：一类是运行或打包文档所需的系统级运行时（如 OpenJDK、Node.js/npm），另一类是项目代码中的API 文档生成库（如 Springfox 或 SpringDoc OpenAPI）。
- 在 CentOS 7/8 上，优先使用 yum/dnf 安装系统依赖；Node 建议通过 NodeSource 仓库安装稳定 LTS 版本，避免系统自带旧版导致依赖冲突。
- 文档展示层（Swagger UI/Editor）建议作为静态资源由 Nginx/Apache 托管，与应用解耦，便于独立升级与访问控制。
二 系统级依赖管理
- OpenJDK 安装与版本固定
- 安装常用版本：sudo yum install -y java-1.8.0-openjdk-devel（或选择 java-11-openjdk-devel）。
- 固定版本避免漂移：使用 alternatives 设置默认 Java，或在应用启动脚本中显式指定 JAVA_HOME。
- Node.js 与 npm（用于 Swagger UI/Editor 前端静态资源）
- 添加 NodeSource 仓库并安装（示例为 Node.js 14.x，可按需调整版本）：
- 安装脚本：curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash -
- 安装命令：sudo yum install -y nodejs
- 验证：node -v、npm -v。
- 使用 YUM 版本锁
- 安装 yum-versionlock 插件，锁定关键包版本（如 nodejs、openjdk），防止系统更新引入不兼容变更：
- 启用锁：sudo yum install -y yum-versionlock
- 加锁示例：sudo yum versionlock add nodejs java-1.8.0-openjdk-devel
- 查看锁：yum versionlock list
- 防火墙放行
- 若文档站点或编辑器运行在 8080/3000/80 等端口，放行对应端口（以 firewalld 为例）：
- 放行端口：sudo firewall-cmd --permanent --add-port=8080/tcp
- 重载规则：sudo firewall-cmd --reload。
三 Java 项目依赖管理
- 使用构建工具集中管理（Maven/Gradle）
- 在 pom.xml 中显式声明版本，避免传递性依赖升级带来不兼容；必要时使用 统一版本。
- Spring Boot 场景
- Springfox（传统，已进入维护模式，建议新项目优先 SpringDoc）
- 典型依赖（示例版本 2.9.2）：
- io.springfox:springfox-swagger2:2.9.2
- io.springfox:springfox-swagger-ui:2.9.2
- 访问路径通常为：http://localhost:8080/swagger-ui.html
- SpringDoc OpenAPI（推荐，适配 Spring Boot 3 / Spring 6，基于 OpenAPI 3）
- 典型依赖（示例版本 1.7.x）：
- org.springdoc:springdoc-openapi-starter-webmvc-ui:1.7.x
- 访问路径通常为：http://localhost:8080/swagger-ui.html（与 Springfox 路径一致，便于迁移）
- 依赖冲突排查
- 使用 mvn dependency:tree 或 gradle dependencies 检查版本冲突；对冲突依赖使用 精确剔除。
- 版本固定与变更控制
- 在 pom.xml 锁定依赖版本；变更通过 语义化版本 与变更记录评审，配合 CI 做兼容性回归测试。
四 Swagger UI 与 Editor 静态资源管理
- 构建与托管
- 方式一：使用 Node.js/npm 安装与启动（适合本地或内网快速使用）
- 克隆并启动编辑器：git clone https://github.com/swagger-api/swagger-editor.git && cd swagger-editor && npm install && npm start
- 访问：http://<服务器IP>:8080
- 方式二：将 Swagger UI 构建后的静态文件（如 swagger-ui-dist）拷贝到 Nginx/Apache 目录（如 /var/www/html/swagger-ui），通过 Web 服务器托管，便于统一鉴权与反向代理。
- 与后端 API 解耦
- 在生产环境中，建议将 UI 静态资源与后端服务分离部署，UI 通过反向代理访问后端 /v3/api-docs（SpringDoc）或 /v2/api-docs（Springfox），避免跨域与版本耦合。
- 安全访问控制
- 通过 Nginx/Apache 配置 Basic Auth 或对接企业 SSO，仅对受控用户开放文档入口；或在应用层结合 Spring Security 对 /swagger-ui/ 路径进行鉴权。
五 版本兼容与升级策略
- Java 与框架矩阵
- Spring Boot 2.x → 可用 Springfox 2.9.x（已进入维护，不建议长期新增依赖）
- Spring Boot 3.x / Spring 6 → 使用 SpringDoc OpenAPI 1.7.x（基于 OpenAPI 3）
- 升级步骤建议
- 评估依赖树与 API 注解变更（如从 @Api 迁移到 @Operation 等）
- 在测试环境验证 /v3/api-docs 输出与 UI 渲染
- 逐步放量，保留回滚方案（如同时保留新旧 UI 路径一段时间）
- 文档即代码
- 将 OpenAPI/Swagger JSON/YAML 纳入代码仓库，配合 Swagger Editor 或 Redocly 做预览与校验，确保文档与实现一致。