欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

從Springfox到SpringDoc OpenAPI的完整遷移指南

 更新時間：2025年08月11日 09:29:39   作者：碼農(nóng)阿豪@新空間  
在SpringBoot項目中,API文檔是前后端協(xié)作的重要橋梁,長期以來,Springfox一直是Java生態(tài)中最流行的API文檔工具之一,但隨著SpringBoot版本的迭代,特別是2.6+版本后,Springfox的兼容性問題逐漸顯現(xiàn),所以本文介紹了從Springfox到SpringDoc OpenAPI的完整遷移指南

引言

在Spring Boot項目中，API文檔是前后端協(xié)作的重要橋梁。長期以來，Springfox（Swagger）一直是Java生態(tài)中最流行的API文檔工具之一。但隨著Spring Boot版本的迭代，特別是2.6+版本后，Springfox的兼容性問題逐漸顯現(xiàn)，導(dǎo)致許多開發(fā)者轉(zhuǎn)向更現(xiàn)代的替代方案——SpringDoc OpenAPI。

本文將詳細(xì)介紹：

  1. Springfox的常見問題（如NullPointerException）
  2. 為何選擇SpringDoc OpenAPI
  3. 完整遷移步驟（含代碼示例）
  4. 最佳實踐與優(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+默認(rèn)使用PathPattern進行路徑匹配，而Springfox 2.x僅支持傳統(tǒng)的AntPathMatcher，導(dǎo)致空指針異常。

1.2 臨時解決方案

在application.properties中強制使用AntPathMatcher：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

但這只是權(quán)宜之計，長期推薦遷移到SpringDoc。

2. 為何選擇SpringDoc OpenAPI？

特性SpringfoxSpringDoc
兼容性僅支持Spring Boot <2.6完美支持Spring Boot 2.6+
注解標(biāo)準(zhǔn)Swagger 2.0OpenAPI 3.0
自動發(fā)現(xiàn)機制有限強大
JWT支持需手動配置內(nèi)置支持
社區(qū)活躍度維護停滯持續(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("手機號碰撞系統(tǒng)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標(biāo)準(zhǔn)：

@RestController
@Tag(name = "手機號管理", description = "手機號碰撞相關(guān)API")
@RequestMapping("/api/phones")
public class PhoneController {

    @Operation(summary = "獲取手機號信息", description = "根據(jù)ID查詢手機號")
    @GetMapping("/{id}")
    public ResponseEntity<Phone> getPhone(
            @Parameter(description = "手機號ID", required = true)
            @PathVariable Long id) {
        // 業(yè)務(wù)邏輯
    }
}

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 "內(nèi)部接口";
}

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掃描路徑內(nèi)

6.2 頁面加載緩慢

  • 清理瀏覽器緩存
  • 禁用SpringDoc的緩存（開發(fā)環(huán)境）：
springdoc.cache.disabled=true

結(jié)語

通過本文，你已完成了從Springfox到SpringDoc的完整遷移。SpringDoc不僅解決了兼容性問題，還提供了更強大的功能。建議所有新項目直接采用SpringDoc，老項目逐步遷移。

最終優(yōu)勢：

  • ? 更好的兼容性
  • ? 更簡潔的配置
  • ? 支持OpenAPI 3.0標(biāo)準(zhǔn)
  • ? 活躍的社區(qū)維護

以上就是從Springfox到SpringDoc OpenAPI的完整遷移指南的詳細(xì)內(nèi)容，更多關(guān)于Springfox到SpringDoc OpenAPI遷移的資料請關(guān)注腳本之家其它相關(guān)文章！

相關(guān)文章

  • SpringBoot使用Redisson實現(xiàn)延遲執(zhí)行的完整示例

    SpringBoot使用Redisson實現(xiàn)延遲執(zhí)行的完整示例

    這篇文章主要介紹了SpringBoot使用Redisson實現(xiàn)延遲執(zhí)行的完整示例,文中通過代碼示例講解的非常詳細(xì),對大家的學(xué)習(xí)或工作有一定的幫助,需要的朋友可以參考下
    2024-06-06
  • Java簡單使用EasyExcel操作讀寫excel的步驟與要點

    Java簡單使用EasyExcel操作讀寫excel的步驟與要點

    相信現(xiàn)在很多搞后端的同學(xué)大部分做的都是后臺管理系統(tǒng),那么管理系統(tǒng)就肯定免不了Excel的導(dǎo)出導(dǎo)入功能,下面這篇文章主要給大家介紹了關(guān)于Java簡單使用EasyExcel操作讀寫excel的步驟與要點,需要的朋友可以參考下
    2022-09-09
  • springboot項目如何部署到服務(wù)器

    springboot項目如何部署到服務(wù)器

    這篇文章主要介紹了springboot項目如何部署到服務(wù)器問題,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教
    2024-05-05
  • SpringBoot如何在運行時動態(tài)添加數(shù)據(jù)源

    SpringBoot如何在運行時動態(tài)添加數(shù)據(jù)源

    這篇文章主要介紹了SpringBoot如何在運行時動態(tài)添加數(shù)據(jù)源,文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友可以參考下
    2019-10-10
  • Java與JavaScript自動化測試Selenium使用詳解

    Java與JavaScript自動化測試Selenium使用詳解

    這篇文章主要介紹了Java與JavaScript自動化測試Selenium的使用,Selenium是一個用于Web應(yīng)用程序測試的工具,Selenium測試直接運行在瀏覽器中,就像真正的用戶在操作一樣,需要的朋友可以參考下
    2025-05-05
  • Java異常處理try?catch的基本用法

    Java異常處理try?catch的基本用法

    try就像一個網(wǎng)，把try{}里面的代碼所拋出的異常都網(wǎng)住，然后把異常交給catch{}里面的代碼去處理。最后執(zhí)行finally之中的代碼。無論try中代碼有沒有異常，也無論catch是否將異常捕獲到，finally中的代碼都一定會被執(zhí)行。
    2021-12-12
  • 解決java編譯錯誤:程序包不存在的問題

    解決java編譯錯誤:程序包不存在的問題

    出錯：Error:(3, 27) java: 程序包com.aliyun.odps.udf不存在，遇到這樣的錯誤問題如何解決呢，下面小編給大家?guī)砹薺ava編譯錯誤:程序包不存在的問題及解決方法，感興趣的朋友一起看看吧
    2023-05-05
  • 使用純java config來配置spring mvc方式

    使用純java config來配置spring mvc方式

    這篇文章主要介紹了使用純java config來配置spring mvc方式，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
    2021-11-11
  • Java之通過OutputStream寫入文件與文件復(fù)制問題

    Java之通過OutputStream寫入文件與文件復(fù)制問題

    這篇文章主要介紹了Java之通過OutputStream寫入文件與文件復(fù)制問題，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
    2023-04-04
  • maven中的maven-antrun-plugin插件示例詳解

    maven中的maven-antrun-plugin插件示例詳解

    maven-antrun-plugin?是?Maven?生態(tài)中一個強大的工具,尤其適合需要復(fù)用?Ant?腳本或?qū)崿F(xiàn)復(fù)雜構(gòu)建邏輯的場景,然而,過度使用可能導(dǎo)致構(gòu)建腳本復(fù)雜化,建議權(quán)衡利弊后合理使用,這篇文章主要介紹了maven中的maven-antrun-plugin插件詳解,需要的朋友可以參考下
    2025-06-06

最新評論