從Springfox到SpringDoc OpenAPI的完整遷移指南
引言
在Spring Boot項(xiàng)目中,API文檔是前后端協(xié)作的重要橋梁。長(zhǎng)期以來(lái),Springfox(Swagger)一直是Java生態(tài)中最流行的API文檔工具之一。但隨著Spring Boot版本的迭代,特別是2.6+版本后,Springfox的兼容性問(wèn)題逐漸顯現(xiàn),導(dǎo)致許多開(kāi)發(fā)者轉(zhuǎn)向更現(xiàn)代的替代方案——SpringDoc OpenAPI。
本文將詳細(xì)介紹:
- Springfox的常見(jiàn)問(wèn)題(如
NullPointerException) - 為何選擇SpringDoc OpenAPI
- 完整遷移步驟(含代碼示例)
- 最佳實(shí)踐與優(yōu)化建議
1. Springfox的常見(jiàn)問(wèn)題
1.1 典型錯(cuò)誤分析
在Spring Boot 2.6+中,啟動(dòng)時(shí)可能遇到以下錯(cuò)誤:
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+默認(rèn)使用PathPattern進(jìn)行路徑匹配,而Springfox 2.x僅支持傳統(tǒng)的AntPathMatcher,導(dǎo)致空指針異常。
1.2 臨時(shí)解決方案
在application.properties中強(qiáng)制使用AntPathMatcher:
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
但這只是權(quán)宜之計(jì),長(zhǎng)期推薦遷移到SpringDoc。
2. 為何選擇SpringDoc OpenAPI?
| 特性 | Springfox | SpringDoc |
|---|---|---|
| 兼容性 | 僅支持Spring Boot <2.6 | 完美支持Spring Boot 2.6+ |
| 注解標(biāo)準(zhǔn) | Swagger 2.0 | OpenAPI 3.0 |
| 自動(dòng)發(fā)現(xiàn)機(jī)制 | 有限 | 強(qiáng)大 |
| JWT支持 | 需手動(dòng)配置 | 內(nèi)置支持 |
| 社區(qū)活躍度 | 維護(hù)停滯 | 持續(xù)更新 |
3. 完整遷移步驟
3.1 移除Springfox依賴
在pom.xml中刪除所有Springfox相關(guān)依賴:
<!-- 移除以下依賴 -->
<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("手機(jī)號(hào)碰撞系統(tǒng)API")
.version("v1.0.0")
.contact(new Contact()
.name("開(kāi)發(fā)團(tuán)隊(duì)")
.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 修改啟動(dòng)類
移除@EnableSwagger2注解:
@SpringBootApplication
public class AppApplication {
public static void main(String[] args) {
SpringApplication.run(AppApplication.class, args);
}
}
3.5 更新Controller注解
替換Swagger注解為OpenAPI 3.0標(biāo)準(zhǔn):
@RestController
@Tag(name = "手機(jī)號(hào)管理", description = "手機(jī)號(hào)碰撞相關(guān)API")
@RequestMapping("/api/phones")
public class PhoneController {
@Operation(summary = "獲取手機(jī)號(hào)信息", description = "根據(jù)ID查詢手機(jī)號(hào)")
@GetMapping("/{id}")
public ResponseEntity<Phone> getPhone(
@Parameter(description = "手機(jī)號(hào)ID", required = true)
@PathVariable Long id) {
// 業(yè)務(wù)邏輯
}
}
4. 高級(jí)配置與優(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 "內(nèi)部接口";
}
5. 遷移后的效果驗(yàn)證
訪問(wèn)Swagger UI:http://localhost:8080/swagger-ui.html
查看OpenAPI JSON:http://localhost:8080/v3/api-docs
驗(yàn)證JWT支持:
在Swagger UI中點(diǎn)擊"Authorize"按鈕,輸入Bearer Token測(cè)試。
6. 常見(jiàn)問(wèn)題解決
6.1 文檔不顯示某些接口
- 檢查是否有
@RequestMapping或@Operation注解 - 確保Controller在Spring掃描路徑內(nèi)
6.2 頁(yè)面加載緩慢
- 清理瀏覽器緩存
- 禁用SpringDoc的緩存(開(kāi)發(fā)環(huán)境):
springdoc.cache.disabled=true
結(jié)語(yǔ)
通過(guò)本文,你已完成了從Springfox到SpringDoc的完整遷移。SpringDoc不僅解決了兼容性問(wèn)題,還提供了更強(qiáng)大的功能。建議所有新項(xiàng)目直接采用SpringDoc,老項(xiàng)目逐步遷移。
最終優(yōu)勢(shì):
- ? 更好的兼容性
- ? 更簡(jiǎn)潔的配置
- ? 支持OpenAPI 3.0標(biāo)準(zhǔn)
- ? 活躍的社區(qū)維護(hù)
以上就是從Springfox到SpringDoc OpenAPI的完整遷移指南的詳細(xì)內(nèi)容,更多關(guān)于Springfox到SpringDoc OpenAPI遷移的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章!
相關(guān)文章
SpringBoot使用Redisson實(shí)現(xiàn)延遲執(zhí)行的完整示例
這篇文章主要介紹了SpringBoot使用Redisson實(shí)現(xiàn)延遲執(zhí)行的完整示例,文中通過(guò)代碼示例講解的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作有一定的幫助,需要的朋友可以參考下2024-06-06
Java簡(jiǎn)單使用EasyExcel操作讀寫(xiě)excel的步驟與要點(diǎn)
相信現(xiàn)在很多搞后端的同學(xué)大部分做的都是后臺(tái)管理系統(tǒng),那么管理系統(tǒng)就肯定免不了Excel的導(dǎo)出導(dǎo)入功能,下面這篇文章主要給大家介紹了關(guān)于Java簡(jiǎn)單使用EasyExcel操作讀寫(xiě)excel的步驟與要點(diǎn),需要的朋友可以參考下2022-09-09
springboot項(xiàng)目如何部署到服務(wù)器
這篇文章主要介紹了springboot項(xiàng)目如何部署到服務(wù)器問(wèn)題,具有很好的參考價(jià)值,希望對(duì)大家有所幫助,如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2024-05-05
SpringBoot如何在運(yùn)行時(shí)動(dòng)態(tài)添加數(shù)據(jù)源
這篇文章主要介紹了SpringBoot如何在運(yùn)行時(shí)動(dòng)態(tài)添加數(shù)據(jù)源,文中通過(guò)示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2019-10-10
Java與JavaScript自動(dòng)化測(cè)試Selenium使用詳解
這篇文章主要介紹了Java與JavaScript自動(dòng)化測(cè)試Selenium的使用,Selenium是一個(gè)用于Web應(yīng)用程序測(cè)試的工具,Selenium測(cè)試直接運(yùn)行在瀏覽器中,就像真正的用戶在操作一樣,需要的朋友可以參考下2025-05-05
解決java編譯錯(cuò)誤:程序包不存在的問(wèn)題
出錯(cuò):Error:(3, 27) java: 程序包c(diǎn)om.aliyun.odps.udf不存在,遇到這樣的錯(cuò)誤問(wèn)題如何解決呢,下面小編給大家?guī)?lái)了java編譯錯(cuò)誤:程序包不存在的問(wèn)題及解決方法,感興趣的朋友一起看看吧2023-05-05
使用純java config來(lái)配置spring mvc方式
這篇文章主要介紹了使用純java config來(lái)配置spring mvc方式,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2021-11-11
Java之通過(guò)OutputStream寫(xiě)入文件與文件復(fù)制問(wèn)題
這篇文章主要介紹了Java之通過(guò)OutputStream寫(xiě)入文件與文件復(fù)制問(wèn)題,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2023-04-04
maven中的maven-antrun-plugin插件示例詳解
maven-antrun-plugin?是?Maven?生態(tài)中一個(gè)強(qiáng)大的工具,尤其適合需要復(fù)用?Ant?腳本或?qū)崿F(xiàn)復(fù)雜構(gòu)建邏輯的場(chǎng)景,然而,過(guò)度使用可能導(dǎo)致構(gòu)建腳本復(fù)雜化,建議權(quán)衡利弊后合理使用,這篇文章主要介紹了maven中的maven-antrun-plugin插件詳解,需要的朋友可以參考下2025-06-06

