木-Star1. 问题现象与背景解析
最近在将一个老项目升级到Spring Boot 2.7时遇到了经典的版本冲突问题：引入springdoc-openapi-ui依赖后启动报错，控制台抛出"Failed to start bean 'documentationPluginsBootstrapper'"异常。这类问题在Spring生态中其实非常典型——当不同库对同一底层组件的版本要求不一致时，就会引发这种"版本不致错误"（Version Inconsistency Error）。
我排查发现项目中同时存在：
xml复制<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
<!-- 老版本swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 根本原因深度剖析
2.1 依赖冲突机制
Spring Boot的自动配置机制会扫描classpath中的库。当同时存在springdoc和springfox时：
- 两者都试图注册OpenAPI相关的Bean
- 对Swagger核心类（如Plugin接口）的版本要求不同
- Spring容器初始化时检测到不兼容的Bean定义
2.2 版本矩阵对照
通过对比两个库的传递依赖：
| 组件 | springdoc 1.6.14要求 | springfox 2.9.2提供 |
|---|---|---|
| spring-plugin-core | 2.0.0+ | 1.2.0 |
| swagger-annotations | 2.2.0 | 1.5.20 |
3. 解决方案实践
3.1 基础解决步骤
- 完全移除springfox相关依赖
xml复制<!-- 必须删除的依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
- 添加纯净的springdoc配置
yaml复制springdoc:
swagger-ui:
path: /api-docs
api-docs:
path: /v3/api-docs
3.2 进阶兼容方案
对于必须保留springfox的老项目：
java复制@Configuration
@ConditionalOnClass(SpringfoxConfig.class)
public class SpringfoxToSpringdocBridge {
@Bean
@Primary
public OpenAPI springfoxOpenApi() {
return new OpenAPI()
.info(new Info().title("兼容API文档"));
}
}
4. 避坑指南
- 依赖树检查技巧
bash复制mvn dependency:tree -Dincludes=spring-plugin,swagger
- 常见报错对照表
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| NoSuchMethodError | 版本混用 | 统一使用springdoc全家桶 |
| BeanCreationException | 重复的Bean定义 | @Primary注解或排除自动配置 |
| ClassNotFoundException | 缺少transitive依赖 | 显式引入springdoc-webmvc |
- 版本选择建议
- Spring Boot 2.4.x → springdoc 1.5.x
- Spring Boot 2.7.x → springdoc 1.6.x
- Spring Boot 3.x → springdoc 2.x
5. 迁移检查清单
- [ ] 删除所有springfox相关的@EnableSwagger2注解
- [ ] 检查是否有自定义的Docket bean
- [ ] 更新单元测试中的MockMvc配置
- [ ] 替换SecurityConfig中的swagger路径白名单
- [ ] 更新CI/CD中的API文档生成脚本
关键提示：在大型项目中建议分阶段迁移，可以先通过profile控制新旧文档的共存，验证无误后再完全移除旧依赖。
经过这次升级，我深刻体会到Spring生态中版本管理的重要性。建议建立项目级的《依赖版本对照表》，特别要注意spring-boot-dependencies中管理的第三方库版本。对于API文档这种基础设施，更推荐使用springdoc这种Spring原生支持的方案，它的OAS 3.0支持度和与Spring Security的集成度都明显优于老旧的springfox。