SpringDoc OpenAPI 与 Spring Boot 3 集成中的常见问题解析

问题背景

在使用 SpringDoc OpenAPI 与 Spring Boot 3 集成时，开发者可能会遇到 javax.xml.bind.annotation.XmlRootElement 类找不到的异常。这个问题通常出现在从旧版本迁移到新版本的过程中，特别是当项目中同时存在新旧版本的依赖时。

核心问题分析

该异常的根本原因是 Java EE 的 JAXB API 在 Java 9 后被标记为废弃，并在后续版本中被移除。Spring Boot 3 基于 Jakarta EE 9+，已经完全迁移到了 jakarta 命名空间下的 API。

解决方案

1. 正确配置依赖

对于 Spring Boot 3 项目，应该只使用 springdoc-openapi-starter-webmvc-ui 依赖，而不是混合使用新旧版本：

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

2. 避免依赖冲突

不要同时引入 springdoc-openapi-ui 和 springdoc-openapi-starter-webmvc-ui，这会导致类加载冲突和不一致的行为。

3. 理解依赖树

正确的依赖树应该显示使用的是 jakarta 命名空间下的 swagger 核心库：

org.springdoc:springdoc-openapi-starter-webmvc-ui
  └─ org.springdoc:springdoc-openapi-starter-webmvc-api
     └─ org.springdoc:springdoc-openapi-starter-common
        └─ io.swagger.core.v3:swagger-core-jakarta

技术原理

Spring Boot 3 完全转向了 Jakarta EE 规范，这意味着：

1. 所有 javax.* 包都被替换为 jakarta.* 包
2. JAXB 等传统 Java EE API 需要显式添加依赖
3. SpringDoc OpenAPI 的 jakarta 版本已经处理了这些迁移问题

最佳实践建议

1. 对于新项目，始终使用最新的 springdoc-openapi-starter-webmvc-ui
2. 迁移项目时，彻底移除旧版本的 springdoc-openapi-ui 依赖
3. 确保项目中其他依赖也兼容 Jakarta EE 规范
4. 定期检查依赖冲突，使用 mvn dependency:tree 分析依赖关系

总结

SpringDoc OpenAPI 与 Spring Boot 3 的集成问题通常源于依赖配置不当。通过正确理解 Jakarta EE 的迁移路径，并遵循官方文档的依赖配置建议，可以避免大多数兼容性问题。记住，在 Spring Boot 3 环境中，应该只使用 springdoc-openapi-starter-webmvc-ui 这一个核心依赖。