引言
在spring boot项目中，api文档是前后端协作的重要桥梁。长期以来，springfox（swagger）一直是java生态中最流行的api文档工具之一。但随着spring boot版本的迭代，特别是2.6+版本后，springfox的兼容性问题逐渐显现，导致许多开发者转向更现代的替代方案——springdoc openapi。
本文将详细介绍：
- springfox的常见问题（如
nullpointerexception） - 为何选择springdoc openapi
- 完整迁移步骤（含代码示例）
- 最佳实践与优化建议
1. springfox的常见问题
1.1 典型错误分析
在spring boot 2.6+中，启动时可能遇到以下错误：
error starting applicationcontext. to display the conditions report re-run your application with 'debug' enabled.
...
caused by: java.lang.nullpointerexception: null
at springfox.documentation.spi.service.contexts.orderings$8.compare(orderings.java:112)
原因：
spring boot 2.6+默认使用pathpattern进行路径匹配，而springfox 2.x仅支持传统的antpathmatcher，导致空指针异常。
1.2 临时解决方案
在application.properties中强制使用antpathmatcher：
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
但这只是权宜之计，长期推荐迁移到springdoc。
2. 为何选择springdoc openapi？
| 特性 | springfox | springdoc |
|---|---|---|
| 兼容性 | 仅支持spring boot <2.6 | 完美支持spring boot 2.6+ |
| 注解标准 | swagger 2.0 | openapi 3.0 |
| 自动发现机制 | 有限 | 强大 |
| jwt支持 | 需手动配置 | 内置支持 |
| 社区活跃度 | 维护停滞 | 持续更新 |
3. 完整迁移步骤
3.1 移除springfox依赖
在pom.xml中删除所有springfox相关依赖：
<!-- 移除以下依赖 -->
<dependency>
<groupid>io.springfox</groupid>
<artifactid>springfox-swagger2</artifactid>
<version>2.9.2</version>
</dependency>
<dependency>
<groupid>io.springfox</groupid>
<artifactid>springfox-swagger-ui</artifactid>
<version>2.9.2</version>
</dependency>
3.2 添加springdoc依赖
<dependency>
<groupid>org.springdoc</groupid>
<artifactid>springdoc-openapi-ui</artifactid>
<version>1.6.14</version>
</dependency>
3.3 替换配置类
将原有的swaggerconfig替换为openapiconfig：
@configuration
public class openapiconfig {
@bean
public openapi customopenapi() {
return new openapi()
.info(new info()
.title("手机号碰撞系统api")
.version("v1.0.0")
.contact(new contact()
.name("开发团队")
.url("https://github.com/your-repo")
.email("dev@example.com")))
.addsecurityitem(new securityrequirement().addlist("bearerauth"))
.components(new components()
.addsecurityschemes("bearerauth",
new securityscheme()
.type(securityscheme.type.http)
.scheme("bearer")
.bearerformat("jwt")));
}
}
3.4 修改启动类
移除@enableswagger2注解：
@springbootapplication
public class appapplication {
public static void main(string[] args) {
springapplication.run(appapplication.class, args);
}
}
3.5 更新controller注解
替换swagger注解为openapi 3.0标准：
@restcontroller
@tag(name = "手机号管理", description = "手机号碰撞相关api")
@requestmapping("/api/phones")
public class phonecontroller {
@operation(summary = "获取手机号信息", description = "根据id查询手机号")
@getmapping("/{id}")
public responseentity<phone> getphone(
@parameter(description = "手机号id", required = true)
@pathvariable long id) {
// 业务逻辑
}
}
4. 高级配置与优化
4.1 分组api文档
@bean
@groupedopenapi
public groupedopenapi userapi() {
return groupedopenapi.builder()
.group("用户管理api")
.pathstomatch("/api/user/")
.build();
}
4.2 自定义swagger ui
在application.properties中配置：
springdoc.swagger-ui.path=/swagger-ui.html springdoc.swagger-ui.operationssorter=alpha springdoc.swagger-ui.tagssorter=alpha springdoc.swagger-ui.doc-expansion=none
4.3 隐藏特定接口
使用@hidden注解：
@hidden
@getmapping("/internal")
public string internalapi() {
return "内部接口";
}
5. 迁移后的效果验证
访问swagger ui：http://localhost:8080/swagger-ui.html
查看openapi json：http://localhost:8080/v3/api-docs
验证jwt支持：
在swagger ui中点击"authorize"按钮，输入bearer token测试。
6. 常见问题解决
6.1 文档不显示某些接口
- 检查是否有
@requestmapping或@operation注解 - 确保controller在spring扫描路径内
6.2 页面加载缓慢
- 清理浏览器缓存
- 禁用springdoc的缓存（开发环境）：
springdoc.cache.disabled=true
结语
通过本文，你已完成了从springfox到springdoc的完整迁移。springdoc不仅解决了兼容性问题，还提供了更强大的功能。建议所有新项目直接采用springdoc，老项目逐步迁移。
最终优势：
- ✅ 更好的兼容性
- ✅ 更简洁的配置
- ✅ 支持openapi 3.0标准
- ✅ 活跃的社区维护
以上就是从springfox到springdoc openapi的完整迁移指南的详细内容，更多关于springfox到springdoc openapi迁移的资料请关注代码网其它相关文章！