centos swagger如何迁移
导读：CentOS 上 Swagger 迁移实操指南 一、迁移场景与总体策略 原地升级：在现有 CentOS 服务器上，把文档方案从 SpringFox/Swagger 2.x 升级到 SpringDoc OpenAPI 3.x，以适配 JDK...
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"
- Maven
- 代码层注解迁移（核心对照）
- @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 - 若项目存在安全拦截器/网关，放行上述路径与静态资源。
- SpringDoc 默认提供 /v3/api-docs 与 /swagger-ui.html；可在 application.yml 调整：
- 常见问题与排查
- 出现 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 - 更新：停止旧容器 → 拉取新镜像 → 重新运行。
- 安装 Docker（CentOS）：
- 手动静态部署（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）快速切回；必要时回滚代码与依赖版本。
声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！
若转载请注明出处： centos swagger如何迁移
本文地址： https://pptw.com/jishu/776991.html