SpringDoc OpenAPI在Spring Boot 3.0.5中的兼容性问题解析

问题背景

在使用Spring Boot 3.0.5版本的项目中，当集成SpringDoc OpenAPI（版本2.3.0）时，应用程序启动过程中出现了java.lang.NoClassDefFoundError: javax/servlet/http/HttpServletRequest异常。这个错误表明系统在运行时无法找到javax.servlet相关的类，这通常与Java EE到Jakarta EE的包名变更有关。

技术分析

根本原因

Spring Boot 3.0及以上版本已经完全迁移到了Jakarta EE 9+，这意味着所有javax.包名都被替换为jakarta.。而SpringDoc OpenAPI 2.3.0版本可能仍然依赖于旧的javax.servlet API，导致在Spring Boot 3.x环境中运行时出现类找不到的错误。

解决方案演进

1. 版本兼容性检查：首先需要确认使用的SpringDoc OpenAPI版本是否与Spring Boot 3.x兼容。对于Spring Boot 3.x，应该使用SpringDoc OpenAPI 2.x的最新版本（如2.1.0+），这些版本已经支持Jakarta EE。

2. 依赖清理：正如用户最终解决方案所示，移除所有旧的SpringDoc OpenAPI相关依赖是解决问题的关键步骤。这包括：

   • 移除可能存在的旧版本springdoc-openapi-core
   • 移除可能存在的springdoc-openapi-webmvc-core等过渡版本

3. 正确依赖配置：对于Spring Boot 3.x项目，应该使用以下依赖配置：

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.1.0</version>
   </dependency>
   

最佳实践建议

1. 版本对齐：始终确保SpringDoc OpenAPI版本与Spring Boot版本匹配。Spring Boot 3.x应该搭配SpringDoc OpenAPI 2.x，而Spring Boot 2.x则使用SpringDoc OpenAPI 1.x。

2. 依赖管理：使用Spring Boot的dependencyManagement来自动管理版本，避免版本冲突：

   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>org.springdoc</groupId>
               <artifactId>springdoc-openapi-starter-parent</artifactId>
               <version>2.1.0</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>
   

3. 迁移注意事项：从Spring Boot 2.x升级到3.x时，除了SpringDoc OpenAPI外，还需要检查：

   • 所有直接或间接依赖的javax.servlet组件
   • 自定义过滤器、监听器等是否使用了正确的jakarta包名
   • 测试用例中的Mock相关导入是否更新

结论

Spring Boot 3.x与Jakarta EE的迁移带来了许多兼容性挑战，SpringDoc OpenAPI的集成问题只是其中之一。通过正确理解版本兼容性、彻底清理旧依赖以及采用适当的依赖管理策略，可以顺利解决这类问题。对于开发者而言，保持依赖库的及时更新和对框架变更的敏感度，是避免类似运行时错误的关键。