springdoc-openapi版本升级指南：从1.x到2.x的平滑迁移
项目地址: https://gitcode.com/gh_mirrors/sp/springdoc-openapi springdoc-openapi 是一款强大的Spring Boot集成库，专为OpenAPI 3规范设计，能够自动生成RESTful API文档。本指南将带你快速掌握从1.x版本升级到2.x版本的核心步骤，避开常见陷阱，实现无缝迁移🚀
📋 版本升级前的准备工作
在开始升级前，请确保你的开发环境满足以下条件：
- Spring Boot版本至少为2.6.x（推荐2.7.x或更高版本）
- JDK版本升级到11或更高
- Maven/Gradle构建工具已更新到最新稳定版
🔄 核心依赖更新步骤
Maven项目升级
打开你的pom.xml文件，替换旧的依赖配置：
<!-- 移除1.x版本依赖 -->
<!-- <dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.15</version>
</dependency> -->
<!-- 添加2.x版本依赖 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
Gradle项目升级
在build.gradle中更新依赖：
// 移除旧依赖
// implementation 'org.springdoc:springdoc-openapi-ui:1.6.15'
// 添加新依赖
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
⚡ 关键API变更与适配方案
1. 配置属性重命名
2.x版本对配置属性进行了标准化重构，主要变更如下：
| 1.x版本属性 | 2.x版本新属性 | 备注 |
|---|---|---|
springdoc.api-docs.path | springdoc.api-docs.path | 保持不变 |
springdoc.swagger-ui.path | springdoc.swagger-ui.path | 保持不变 |
springdoc.group-configs[0].group | springdoc.group-configs[0].group | 保持不变 |
springdoc.writer-with-default-pretty-printer | springdoc.api-docs.pretty-print | 功能相同 |
2. 分组API配置方式优化
在2.x版本中，GroupedOpenApi的构建方式更加直观：
// 2.x版本推荐写法
@Bean
public GroupedOpenApi userApi() {
return GroupedOpenApi.builder()
.group("users")
.pathsToMatch("/api/users/**")
.addOpenApiCustomizer(customizer -> {
customizer.info(new Info()
.title("User API")
.version("v1")
.description("User management API"));
})
.build();
}
3. 已废弃API替代方案
| 1.x已废弃API | 2.x替代方案 | 迁移指导 |
|---|---|---|
OpenAPIBuilder | OpenAPI直接构建 | 使用new OpenAPI()创建实例 |
SpringDocUtils.getConfig() | SpringDocConfigProperties | 通过@Autowired注入配置属性 |
SwaggerUiConfigParameters | SwaggerUiConfigProperties | 配置类重命名，属性保持兼容 |
🛠️ 常见问题解决方案
问题1：Swagger UI无法访问
症状：升级后访问/swagger-ui.html返回404错误
解决方法：检查是否使用了正确的starter依赖：
- WebMvc项目：使用
springdoc-openapi-starter-webmvc-ui - WebFlux项目：使用
springdoc-openapi-starter-webflux-ui
问题2：自定义OpenAPI配置不生效
症状：自定义的OpenAPI Bean未被正确加载
解决方法：确保配置类上添加了@Configuration注解，并直接返回OpenAPI对象：
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("My API")
.version("v1")
.description("API documentation"));
}
}
问题3： actuator端点文档丢失
症状：升级后/actuator端点的API文档不再显示
解决方法：添加actuator专用依赖：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-actuator-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
✅ 验证升级结果的关键步骤
- 启动应用：检查控制台输出，确认springdoc相关Bean正常加载
- 访问API文档：打开
http://localhost:8080/swagger-ui/index.html - 验证分组配置：如果使用了
GroupedOpenApi，检查分组切换功能是否正常 - 测试API调用：通过Swagger UI测试几个关键API，确保请求响应格式正确
- 检查日志：确认没有springdoc相关的警告或错误日志
📚 进阶配置与最佳实践
自定义API处理器
2.x版本提供了更灵活的API自定义机制：
@Component
public class CustomOpenApiCustomizer implements OpenApiCustomizer {
@Override
public void customise(OpenAPI openApi) {
// 添加全局安全方案
openApi.addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
.components(new Components()
.addSecuritySchemes("bearerAuth",
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")));
}
}
性能优化建议
对于大型项目，建议进行以下优化：
- 限制扫描路径：通过
springdoc.packages-to-scan指定需要扫描的包 - 禁用默认文档：设置
springdoc.api-docs.enabled=false关闭默认文档 - 使用延迟加载：对非关键API分组启用延迟加载
🎯 总结与注意事项
springdoc-openapi 2.x版本通过模块化设计提供了更好的扩展性和兼容性，升级过程主要涉及：
- 更新依赖坐标和版本号
- 调整配置属性名称
- 适配API分组配置方式
- 替换已废弃的类和方法
迁移过程中，建议先在测试环境验证所有API文档的生成情况，特别注意检查自定义配置和扩展点。如有疑问，可以参考官方文档或提交issue获取支持。
祝你的升级过程顺利！如有任何问题，欢迎在项目的GitHub仓库提交issue反馈。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
