155 lines
3.9 KiB
Markdown
155 lines
3.9 KiB
Markdown
# SpringDoc OpenAPI 迁移报告
|
||
|
||
## 迁移概述
|
||
|
||
已成功将项目从 **Springfox 3.0.0** 迁移到 **SpringDoc OpenAPI 1.7.0**，解决了与 Spring Boot 2.6+ 的兼容性问题。
|
||
|
||
## ✅ 已完成的迁移工作
|
||
|
||
### 1. 依赖更新
|
||
- ✅ **Springfox → SpringDoc OpenAPI**
|
||
```xml
|
||
<!-- 旧依赖 -->
|
||
<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 升级**
|
||
```xml
|
||
<!-- 旧版本 -->
|
||
<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. 注解迁移示例
|
||
- ✅ **控制器注解**
|
||
```java
|
||
// 旧注解
|
||
@Api(tags = "文章管理")
|
||
@ApiOperation("分页查询文章")
|
||
|
||
// 新注解
|
||
@Tag(name = "文章管理")
|
||
@Operation(summary = "分页查询文章")
|
||
```
|
||
|
||
- ✅ **实体类注解**
|
||
```java
|
||
// 旧注解
|
||
@ApiModel(value = "CmsModel对象", description = "模型")
|
||
@ApiModelProperty(value = "ID")
|
||
|
||
// 新注解
|
||
@Schema(name = "CmsModel对象", description = "模型")
|
||
@Schema(description = "ID")
|
||
```
|
||
|
||
### 4. 配置优化
|
||
- ✅ 移除了不兼容的 `SpringFoxSwaggerHostResolver`
|
||
- ✅ 添加了 `ant_path_matcher` 兼容性配置
|
||
- ✅ 临时禁用了 API 文档功能（等待重新编译）
|
||
|
||
## ⏳ 待完成的工作
|
||
|
||
### 1. 重新编译项目
|
||
**重要：** 当前 JAR 文件仍包含旧的 Springfox 依赖，需要重新编译：
|
||
|
||
```bash
|
||
# 安装 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 注解，可以使用提供的脚本批量迁移：
|
||
|
||
```bash
|
||
# 使用迁移脚本
|
||
chmod +x migrate_swagger_annotations.sh
|
||
./migrate_swagger_annotations.sh
|
||
```
|
||
|
||
### 3. 启用 API 文档
|
||
重新编译后，在 `application.yml` 中启用 SpringDoc：
|
||
|
||
```yaml
|
||
# 启用 SpringDoc OpenAPI
|
||
springdoc:
|
||
api-docs:
|
||
enabled: true
|
||
swagger-ui:
|
||
enabled: true
|
||
|
||
# 启用 Knife4j
|
||
knife4j:
|
||
enable: true
|
||
```
|
||
|
||
## 🎯 迁移后的优势
|
||
|
||
1. **兼容性**: 完美支持 Spring Boot 2.6+ 和 3.x
|
||
2. **性能**: 更快的启动速度和更好的运行时性能
|
||
3. **标准化**: 使用标准 OpenAPI 3.0 规范
|
||
4. **维护性**: 活跃的社区支持和定期更新
|
||
5. **简化配置**: 零配置即可使用，配置更简洁
|
||
|
||
## 📋 验证清单
|
||
|
||
重新编译后需要验证：
|
||
|
||
- [ ] 应用正常启动无错误
|
||
- [ ] 访问 Swagger UI: `http://localhost:9200/swagger-ui.html`
|
||
- [ ] 访问 API 文档: `http://localhost:9200/v3/api-docs`
|
||
- [ ] 访问 Knife4j UI: `http://localhost:9200/doc.html`
|
||
- [ ] 各模块分组正常显示
|
||
- [ ] JWT 认证配置正常工作
|
||
|
||
## 🔧 故障排除
|
||
|
||
如果遇到问题：
|
||
|
||
1. **编译错误**: 检查是否有遗漏的注解迁移
|
||
2. **启动失败**: 确认所有 Springfox 依赖已移除
|
||
3. **文档不显示**: 检查 SpringDoc 配置是否正确启用
|
||
4. **认证问题**: 验证 JWT 配置是否正确
|
||
|
||
## 📝 注意事项
|
||
|
||
- 迁移脚本会创建 `.bak` 备份文件，如有问题可以恢复
|
||
- 建议在测试环境先验证完整功能后再部署到生产环境
|
||
- 新的 API 文档 URL 可能与旧版本不同，需要更新相关文档
|