SpringDoc OpenAPI 与 Spring Boot 3.4 兼容性问题解析

问题背景

SpringDoc OpenAPI 是一个流行的 Spring Boot 项目文档生成工具，它能够自动为基于 Spring 的 REST API 生成 OpenAPI 3.0 文档。近期有开发者反馈，在将 Spring Boot 从 3.3.3 升级到 3.4.0-M2 版本后，SpringDoc OpenAPI 的 WebFlux UI 界面无法正常加载 API 定义，出现了"Failed to fetch /v3/api-docs"的错误。

问题现象

升级到 Spring Boot 3.4.0-M2 后，开发者观察到以下现象：

1. Swagger UI 界面骨架能够正常渲染
2. API 列表无法加载
3. 浏览器控制台显示"Failed to fetch /v3/api-docs"错误
4. 服务器日志中抛出 NoSuchMethodError 异常

根本原因分析

经过深入调查，发现问题源于 Spring Framework 6.2 版本中对 ControllerAdviceBean 构造函数的修改。具体表现为：

1. Spring Boot 3.4.0-M2 依赖 Spring Framework 6.2
2. Spring Framework 6.2 中 ControllerAdviceBean 的构造函数发生了变化
3. SpringDoc OpenAPI 2.6.0 版本中的 GenericResponseService 类仍然使用旧的构造函数方式
4. 当项目中使用 @RestControllerAdvice 时，这个问题尤为明显

技术细节

问题的核心在于 GenericResponseService 类中的 getGenericMapResponse 方法。该方法尝试通过 ControllerAdviceBean 的构造函数来检查控制器通知的适用性，但新版本的 Spring Framework 已经修改了这个构造函数的签名。

解决方案

对于不同版本的 Spring Boot，推荐以下解决方案：

1. Spring Boot 3.4.x 用户：升级到 SpringDoc OpenAPI 2.8.3 或更高版本
2. 等待正式发布：Spring Boot 3.4 尚未正式发布，建议等待官方兼容性更新
3. 临时解决方案：如果问题由自定义的 @RestControllerAdvice 引起，可以暂时注释掉相关代码

最佳实践建议

1. 在升级 Spring Boot 版本前，先检查 SpringDoc OpenAPI 的兼容性说明
2. 对于生产环境，建议等待 Spring Boot 正式发布后再进行升级
3. 考虑在 CI/CD 流程中加入 API 文档生成的验证步骤
4. 关注 SpringDoc OpenAPI 的更新日志，及时获取兼容性修复信息

总结

Spring 生态系统的持续演进带来了许多改进，但同时也可能引入一些兼容性问题。SpringDoc OpenAPI 与 Spring Boot 3.4 的兼容性问题提醒我们，在升级框架版本时需要全面考虑依赖组件的兼容性。通过理解问题的根本原因和解决方案，开发者可以更从容地应对类似的技术挑战。