小程序开发-服务端

3.9 KiB

Raw Permalink Blame History

SpringDoc OpenAPI 迁移报告

迁移概述

已成功将项目从 Springfox 3.0.0 迁移到 SpringDoc OpenAPI 1.7.0，解决了与 Spring Boot 2.6+ 的兼容性问题。

✅ 已完成的迁移工作

1. 依赖更新

✅ Springfox → SpringDoc OpenAPI

<!-- 旧依赖 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

<!-- 新依赖 -->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.7.0</version>
</dependency>

✅ Knife4j 升级

<!-- 旧版本 -->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>3.0.3</version>
</dependency>

<!-- 新版本 -->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
  <version>4.3.0</version>
</dependency>

2. 配置类重写

✅ SwaggerConfig.java 完全重写
- 使用 OpenAPI 替代 Docket
- 使用 GroupedOpenApi 实现模块分组
- 配置 JWT Bearer 认证
- 支持 common、cms、shop、oa、other 模块分组

3. 注解迁移示例

✅ 控制器注解

// 旧注解
@Api(tags = "文章管理")
@ApiOperation("分页查询文章")

// 新注解
@Tag(name = "文章管理")
@Operation(summary = "分页查询文章")

✅ 实体类注解

// 旧注解
@ApiModel(value = "CmsModel对象", description = "模型")
@ApiModelProperty(value = "ID")

// 新注解
@Schema(name = "CmsModel对象", description = "模型")
@Schema(description = "ID")

4. 配置优化

✅ 移除了不兼容的 SpringFoxSwaggerHostResolver
✅ 添加了 ant_path_matcher 兼容性配置
✅ 临时禁用了 API 文档功能（等待重新编译）

⏳ 待完成的工作

1. 重新编译项目

重要： 当前 JAR 文件仍包含旧的 Springfox 依赖，需要重新编译：

# 安装 Maven（如果没有）
brew install maven  # macOS
# 或
sudo apt install maven  # Ubuntu

# 重新编译项目
mvn clean package -DskipTests

# 运行新版本
java -jar target/com-gxwebsoft-modules-1.5.0.jar

2. 批量注解迁移

项目中还有大量文件使用旧的 Springfox 注解，可以使用提供的脚本批量迁移：

# 使用迁移脚本
chmod +x migrate_swagger_annotations.sh
./migrate_swagger_annotations.sh

3. 启用 API 文档

重新编译后，在 application.yml 中启用 SpringDoc：

# 启用 SpringDoc OpenAPI
springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

# 启用 Knife4j
knife4j:
  enable: true

🎯 迁移后的优势

兼容性: 完美支持 Spring Boot 2.6+ 和 3.x
性能: 更快的启动速度和更好的运行时性能
标准化: 使用标准 OpenAPI 3.0 规范
维护性: 活跃的社区支持和定期更新
简化配置: 零配置即可使用，配置更简洁

📋 验证清单

重新编译后需要验证：

应用正常启动无错误
访问 Swagger UI: http://localhost:9200/swagger-ui.html
访问 API 文档: http://localhost:9200/v3/api-docs
访问 Knife4j UI: http://localhost:9200/doc.html
各模块分组正常显示
JWT 认证配置正常工作

🔧 故障排除

如果遇到问题：

编译错误: 检查是否有遗漏的注解迁移
启动失败: 确认所有 Springfox 依赖已移除
文档不显示: 检查 SpringDoc 配置是否正确启用
认证问题: 验证 JWT 配置是否正确

📝 注意事项

迁移脚本会创建 .bak 备份文件，如有问题可以恢复
建议在测试环境先验证完整功能后再部署到生产环境
新的 API 文档 URL 可能与旧版本不同，需要更新相关文档

3.9 KiB Raw Permalink Blame History