告別Swagger UI！一款更適合 SpringBoot 的API文檔新選擇

Java精選面試題（微信小程序）：5000+道面試題和選擇題，包含Java基礎、并發、JVM、線程、MQ系列、Redis、Spring系列、Elasticsearch、Docker、K8s、Flink、Spark、架構設計、大廠真題等，在線隨時刷題！

SpringDoc是什么

SpringDoc 是一個專為 Spring Boot 應用設計的庫，能夠自動生成符合 OpenAPI 3 規范的 API 文檔。它通過掃描項目中的控制器、方法注解及配置，動態生成 JSON/YAML/HTML 格式的文檔，并提供交互式界面（如 Swagger UI）供開發者查看和測試 API

與Swagger的關系

Swagger 作為 OpenAPI 規范的前身，貢獻了 API 設計理念并推動了 OpenAPI 的標準化。其核心工具 Swagger UI 用于展示交互式文檔。

SpringDoc 并非 Swagger 的替代品，而是基于 OpenAPI 3 規范的實現工具，并天然集成 Swagger UI 作為文檔展示界面

為什么要選擇SpringDoc

在SpringDoc面世之前，Spring生態中集成實現Swagger的技術為SpringFox，SpringFox與Swagger之間的協作關系如下

SpringFox

• ? 代碼掃描：SpringFox 在運行時掃描 Spring MVC 控制器（如@RestController）、方法注解（如@RequestMapping）以及 Swagger 專用注解（如@ApiOperation），提取接口的路徑、參數、響應等信息

• ? 生成 OpenAPI 規范文檔： 將掃描結果轉換為符合 Swagger 2.0 或 OpenAPI 3.0 規范的 JSON 文件

• ? 集成 Spring 生態，提供 Docket 配置類，支持自定義接口掃描范圍（如包路徑、URL 匹配規則）和文檔信息（如標題、版本、作者）

• ? 可視化文檔渲染：將 SpringFox 生成的 JSON 文件解析為交互式網頁，通過瀏覽器訪問（如http://localhost:8080/swagger-ui.html）

• ? 提供接口列表、參數說明、請求示例，并支持在線測試 API（可直接發送請求并查看響應）

• ? 標準化規范支持：Swagger 定義 OpenAPI 規范（原 Swagger 規范），為 API 描述提供統一標準（如接口路徑、請求方法、數據類型），SpringFox 生成的 JSON 文件完全遵循此規范，確保與其他 Swagger 工具（如Swagger Editor）兼容

• ? 開發階段：開發者在 Spring 控制器中添加 Swagger 注解（如@Api、@ApiParam），描述接口細節

• ? 運行時：SpringFox 掃描代碼并生成 JSON 文檔

• ? 展示階段：Swagger UI 讀取 JSON 文件，渲染為可視化界面供團隊使用

在2020時，由于SpringFox官方基本停止維護，不再發布新版本或修復問題，再加上他無法適配 Spring Boot 2.6+ 及 3.x 版本，導致與新版本 Spring 生態沖突（如路徑匹配失效、注解不兼容）。以及配置的復雜性導致他逐漸退出市場

轉而由更新的技術–SpringDoc接過接力棒，SpringDoc完美支持 Spring Boot 2.6+ 及 3.x（含 JDK 17+），并且原生支持OpenAPI 3 規范，除此之外，如果不需要特殊的復雜配置，甚至可以零配置，僅需引入一個依賴，即可實現開箱即用，還有他直接使用 JSR-303 規范注解（如@Schema、@Parameter），替代 SpringFox 的專屬注解（如@ApiModel），降低了開發人員的學習成本

正式發布

最小化配置使用

不多說廢話了，下面我們正式開始，首先我們先介紹最簡單，最小化的引入以及使用方式

第一步：引入Jar包

     

 org.springdoc groupId>     

 springdoc-openapi-starter-webmvc-ui artifactId>     

 2.5.0 version>  dependency>

第二步：配置配置文件

正常使用SpringDoc，或多或少都會進行一些配置文件的配置，但是由于這里是進行最小化配置，所以這里不進行配置文件配置，僅僅介紹幾個重要配置的默認項，給大家一個基礎印象，方便大家理解后面運行時為什么要這樣做，當然，如果不感興趣的小伙伴也可以直接跳過，跟著步驟走，并不影響使用

# application.yml springdoc: # SpringDoc的API包掃描路徑，如果不配置，SpringDoc 自動掃描整個項目類路徑，它會自動識別所有 @RestController、@RequestMapping 等注解，生成 API 文檔 packages-to-scan:com.example.controller swagger-ui:     # 是否開啟swagger界面，依賴OpenApi，默認為true，如果要開啟需要OpenApi同時開啟     enabled:true     # 內置 Swagger UI 的訪問路徑，默認值為/swagger-ui/index.html     path:/swagger-ui/index.html     # 指定OpenAPI文檔的URL（注意這里一定要與api-docs.path保持一致，否則會請求失敗）     url:/v3/api-docs     # 是否禁用Swagger UI自帶的示例接口（如 Petstore 等默認接口），默認值為false，僅展示當前項目的 API     disable-swagger-default-url:false api-docs:     # 是否啟用OpenAPI文檔端點，默認為true     enabled:true     # OpenAPI 3規范的文檔訪問路徑，默認值為/v3/api-docs     path: /api-docs

第三步：添加一個配置類，用于設置Swagger-UI頁面的一些基礎信息的展示

@Configuration @OpenAPIDefinition(info = @Info(     title = "項目API文檔",     version = "1.0",     description = "SpringBoot項目接口文檔" )) public class SpringDocConfig {     // 無需額外配置，注解已定義基本信息 }

到這一步：其實已經可以訪問頁面，觀看效果了（訪問鏈接為：http://localhost:8080/swagger-ui/index.html，注意如果上方配置文件修改了，這里要替換為對應的鏈接，我這里沒有修改所以使用默認鏈接），只是項目如果沒有任何controller，這里會展示空頁面，如下：

第四步：在需要顯示的Controller方法上加上注解，用于給方法添加備注，如下會展示不加注解與加注解的區別

不加注解：

@RestController @RequestMapping("/main") public class MainController {     @GetMapping("/index")     public String index(String str1) {         return "請求成功";     } }

添加注解

@RestController @RequestMapping("/main") @Tag(name = "演示controller", description = "演示controller") public class MainController {     @GetMapping("/index")     @Operation(summary = "演示方法", description = "演示方法的注釋")     public String index(             @Parameter(description = "參數1", required = true) String str1) {         return "請求成功";     } }

至此為止，SpringDoc的最小化使用已經全部完成（請注意，以上所有配置生效的前提是，當前Spring項目未添加任何過濾器、攔截器，以及未使用SpringSecurity等安全框架，否則，僅僅進行最小化配置是無法運行的，因為一些默認配置可能會被攔截，如果需要更復雜配置，請繼續往下看）

SpringDoc中簡單分組配置（包含編程式配置與聲明式配置）

上方僅僅只是展示了SpringDoc的最基礎用法，接下來，我們展示SpringDoc的一種常用用法：分組，先上效果圖，讓大家了解是個什么功能

接下來開始進行詳細配置：

方式一：編程式配置（靈活性高、擴展性強、調試友好）

@Configuration @OpenAPIDefinition(info = @Info(         title = "項目API文檔",         version = "1.0",         description = "SpringBoot項目接口文檔" )) publicclassSpringDocConfig {     /**      * 商品分組的配置（使用請求路徑掃描的方式進行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi userGroup() {         // 使用路徑匹配方式：僅包含 /api/product/** 下的接口         return GroupedOpenApi.builder()                 .group("商品模塊")                 .pathsToMatch("/api/product/**")   // 路徑匹配                 .build();     }     /**      * 會員分組的配置（使用包掃描的方式進行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi productGroup() {         // 使用包掃描方式：掃描 com.ren.main.controller.member 包下的所有接口         return GroupedOpenApi.builder()                 .group("用戶模塊")                 .packagesToScan("com.ren.main.controller.member") // 包掃描                 .build();     } }

這種配置方式的原理是通過添加GroupedOpenApi類型的Bean，項目啟動時，SpringDoc會尋找環境中是否存在GroupedOpenApi類型的Bean，如果存在，則會創建分組進行展示

注意：

• ? 一旦這里配置了分組方式展示，那么在application.yml配置文件中配置的springdoc.packages-to-scan就會失效，因為SpringDoc的掃描機制，分組配置的掃描路徑優先級大于配置文件配置的掃描優先級

• ? 路徑掃描有兩種方式，一種是根據請求路徑進行掃描，一種是根據包路徑進行掃描，上方都有進行配置

• ? 如果多個分組中有重合的路徑，也就是說一個接口在多個分組配置的路徑中都能掃描到，那么這個接口會存在于多個分組中

以下展示我的代碼結構，方便大家理解：

大家會發現，我的目錄中有一個MainController的內容，在頁面中沒有展示了，這是為什么呢？原因我上面提過了，因為分組的配置會覆蓋默認配置與配置文件配置，而分組配置中由于沒有包含MainController的內容，所以，MainController的內容沒有地方展示了

那么如果想要展示出這個文件中的接口該怎么辦呢？很簡單，在分組中再加一個默認分組，用于展示所有接口內容即可，如下

@Configuration @OpenAPIDefinition(info = @Info(         title = "項目API文檔",         version = "1.0",         description = "SpringBoot項目接口文檔" )) publicclassSpringDocConfig {     /**      * 默認分組      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:38      */     @Bean     public GroupedOpenApi defaultGroup() {         return GroupedOpenApi.builder()                 .group("默認分組")                 .pathsToMatch("/**")   // 路徑匹配                 .build();     }     /**      * 商品分組的配置（使用請求路徑掃描的方式進行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi userGroup() {         // 使用路徑匹配方式：僅包含 /api/product/** 下的接口         return GroupedOpenApi.builder()                 .group("商品模塊")                 .pathsToMatch("/api/product/**")   // 路徑匹配                 .build();     }     /**      * 會員分組的配置（使用包掃描的方式進行配置）      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:17      */     @Bean     public GroupedOpenApi productGroup() {         // 使用包掃描方式：掃描 com.ren.main.controller.member 包下的所有接口         return GroupedOpenApi.builder()                 .group("用戶模塊")                 .packagesToScan("com.ren.main.controller.member") // 包掃描                 .build();     } }

配置后展示的內容

看上面的圖，MainController的內容展示在這里了，同時ProductController和MemberController的內容也展示在這里了，這是為什么呢，原因我上面說過了，如果一個請求被多個分組掃描到，那么他會展示在多個分組中

方式二：聲明式配置（配置集中管理、可使用多配置文件進行環境隔離）

springdoc:   group-configs:     -group:'默認分組'       paths-to-match:'/**'     -group:'商品模塊'       paths-to-match:'/api/product/**'     -group:'用戶模塊'       packages-to-scan: 'com.ren.main.controller.member'

如上：效果與方式一相同

如果項目中重寫了WebMvcConfigurer的addResourceHandlers方法，所需進行的處理

WebMvcConfigurer

WebMvcConfigurer是 Spring MVC 的配置中樞，用于定制化 Spring MVC 的各種行為。它不是過濾器或攔截器，而是一個配置接口（類似汽車的儀表盤），讓你調整 Spring MVC 的運行方式。

他所擁有的方法

• ?addInterceptors(registry)：注冊攔截器

• ?addCorsMappings(registry)：配置跨域權限

• ?addResourceHandlers(registry)：指定靜態資源路徑

• ?addViewControllers(registry)：設置簡易頁面跳轉

• ?configureMessageConverters(list)：定制JSON/XML解析器

• ?configurePathMatch(configurer)：調整URL匹配規則

• ?addArgumentResolvers(list)：自定義請求參數處理器

• ?addReturnValueHandlers(list)：自定義返回值處理器

• ?configureContentNegotiation(configurer)：內容協商配置（響應格式協商）

如果我們重寫了WebMvcConfigurer的addResourceHandlers方法，那么原本Spring自己默認配置的所有的靜態資源的指向路徑就全都會失效，于是就需要我們自己去配置指定

@Configuration publicclassResourcesConfigimplementsWebMvcConfigurer {     @Override     publicvoidaddResourceHandlers(ResourceHandlerRegistry registry) {         registry.addResourceHandler("/swagger-ui/**")             .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")             .setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());     } }

按照如上設置后，SpringDoc將恢復正常（注意新版的SpringDoc和老版的SpringFox配置有所區別，這里只展示新版SpringDoc的配置方法）如果大家對老版配置有需要，可以留言，留言人多會單獨出一期

如果項目引入了SpringSecurity需要進行的處理

由于項目引入了SpringSecurity，導致如果項目不經過認證無法訪問系統資源，我們就需要在SpringSecurity的配置文件中放開SpringDoc相關的靜態資源的攔截，如下

@Configuration @EnableWebSecurity @EnableMethodSecurity publicclassSecurityConfig {     /*      * 配置過濾器鏈      * @param http      * @return org.springframework.security.web.SecurityFilterChain      * @author ren      * @date 2025/04/17 21:30      */     @Bean     public SecurityFilterChain securityFilterChain(HttpSecurity http)throws Exception {         http.authorizeHttpRequests(auth -> auth                 // 允許 OPTIONS 方法通過                 .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()                 // 靜態資源，可匿名訪問                 .requestMatchers(request -> {                     Stringpath= request.getServletPath();                     return (request.getMethod().equals("GET") && ( "/".equals(path) || path.endsWith(".html") || path.endsWith(".css") || path.endsWith(".js")));                 }).permitAll()                 .requestMatchers("/swagger-ui/**", "/*/api-docs/**", "/swagger-resources/**", "/webjars/**", "/druid/**")                 .permitAll()                 // 除上面外的所有請求全部需要鑒權認證                 .anyRequest().authenticated()         );         return http.build();     } }

添加如上配置后，即可放開SpringSecurity的認證限制

總結

以上就是今天要講的內容，本文簡單介紹了SpringDoc整合在SpringBoot項目中的步驟，如果有遺漏，請大家留言，看到后會進行補充。

作者：犯困嫌疑人(づ ●─● )づ

https://blog.csdn.net/2503_92695612

公眾號“Java精選”所發表內容注明來源的，版權歸原出處所有（無法查證版權的或者未注明出處的均來自網絡，系轉載，轉載的目的在于傳遞更多信息，版權屬于原作者。如有侵權，請聯系，筆者會第一時間刪除處理！

最近有很多人問，有沒有讀者交流群！加入方式很簡單，公眾號Java精選，回復“加群”，即可入群！

文章有幫助的話，點在看，轉發吧！