從Springfox到SpringDoc OpenAPI的完整遷移指南
更新時間：2025年08月11日 09:29:39 作者：碼農阿豪@新空間
在SpringBoot項目中,API文檔是前后端協作的重要橋梁,長期以來,Springfox一直是Java生態(tài)中最流行的API文檔工具之一,但隨著SpringBoot版本的迭代,特別是2.6+版本后,Springfox的兼容性問題逐漸顯現,所以本文介紹了從Springfox到SpringDoc OpenAPI的完整遷移指南
引言
在Spring Boot項目中，API文檔是前后端協作的重要橋梁。長期以來，Springfox（Swagger）一直是Java生態(tài)中最流行的API文檔工具之一。但隨著Spring Boot版本的迭代，特別是2.6+版本后，Springfox的兼容性問題逐漸顯現，導致許多開發(fā)者轉向更現代的替代方案——SpringDoc OpenAPI。
本文將詳細介紹：
- Springfox的常見問題（如
NullPointerException） - 為何選擇SpringDoc OpenAPI
- 完整遷移步驟（含代碼示例）
- 最佳實踐與優(yōu)化建議
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 |
| 自動發(fā)現機制 | 有限 | 強大 |
| JWT支持 | 需手動配置 | 內置支持 |
| 社區(qū)活躍度 | 維護停滯 | 持續(xù)更新 |
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("開發(fā)團隊")
.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) {
// 業(yè)務邏輯
}
}
4. 高級配置與優(yōu)化
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的緩存（開發(fā)環(huán)境）：
springdoc.cache.disabled=true
結語
通過本文，你已完成了從Springfox到SpringDoc的完整遷移。SpringDoc不僅解決了兼容性問題，還提供了更強大的功能。建議所有新項目直接采用SpringDoc，老項目逐步遷移。
最終優(yōu)勢：
- ? 更好的兼容性
- ? 更簡潔的配置
- ? 支持OpenAPI 3.0標準
- ? 活躍的社區(qū)維護
以上就是從Springfox到SpringDoc OpenAPI的完整遷移指南的詳細內容，更多關于Springfox到SpringDoc OpenAPI遷移的資料請關注腳本之家其它相關文章！
相關文章
本文介紹了在Spring Cloud Gateway中修改HTTP請求頭的方法,包括直接操作ServerHttpRequest對象和創(chuàng)建自定義Request請求包裝類兩種方式,此方法可用于替換Authorization請求頭中的token2026-04-04
這篇文章主要給大家介紹了關于spring boot啟動時加載外部配置文件的相關資料，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧。2018-02-02
這篇文章主要介紹了Thymeleaf中th:each及th:if使用方法解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2020-08-08
這篇文章主要為大家詳細介紹了Java堆排序算法的相關代碼，具有一定的參考價值，感興趣的小伙伴們可以參考一下2017-09-09
這篇文章主要介紹了java IO流讀取圖片供前臺顯示代碼分享，具有一定借鑒價值，需要的朋友可以參考下。2017-12-12
SpringBoot中的五種對靜態(tài)資源的映射規(guī)則的實現
這篇文章主要介紹了SpringBoot中的五種對靜態(tài)資源的映射規(guī)則的實現，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-12-12
這篇文章介紹了Java指令重排在多線程環(huán)境下的解決方式，文中通過示例代碼介紹的非常詳細。對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下2022-04-04
Java中抽象類和接口的區(qū)別_動力節(jié)點Java學院整理
java抽象類和接口最本質的區(qū)別是接口里不能實現方法--接口中的方法全是抽象方法。抽象類中可實現方法--抽象類中的方法可以不是抽象方法，下文給大家簡單介紹下，需要的的朋友參考下2017-04-04
Lombok是一個可以通過簡單的注解形式，來幫助我們簡化消除一些必須有但顯得很臃腫（如果getter、setter方法）的Java代碼的工具，通過使用對應的注解，可以在編譯源碼的時候生成對應的方法，這篇文章主要介紹了Lombok在idea中的使用,需要的朋友可以參考下2023-03-03
Java中的List集合是一種常用的數據結構,它提供了一種有序、可重復的元素集合,下面這篇文章主要給大家介紹了關于Java基礎篇之List集合的相關資料,文中通過代碼介紹的非常詳細,需要的朋友可以參考下2024-03-03