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

SpringDoc是什么

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

與Swagger的關(guān)系

Swagger 作為 OpenAPI 規(guī)范的前身，貢獻(xiàn)了 API 設(shè)計理念并推動了 OpenAPI 的標(biāo)準(zhǔn)化。其核心工具 Swagger UI 用于展示交互式文檔。

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

為什么要選擇SpringDoc

在SpringDoc面世之前，Spring生態(tài)中集成實現(xiàn)Swagger的技術(shù)為SpringFox，SpringFox與Swagger之間的協(xié)作關(guān)系如下

SpringFox

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

• ? 生成 OpenAPI 規(guī)范文檔： 將掃描結(jié)果轉(zhuǎn)換為符合 Swagger 2.0 或 OpenAPI 3.0 規(guī)范的 JSON 文件

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

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

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

• ? 標(biāo)準(zhǔn)化規(guī)范支持：Swagger 定義 OpenAPI 規(guī)范（原 Swagger 規(guī)范），為 API 描述提供統(tǒng)一標(biāo)準(zhǔn)（如接口路徑、請求方法、數(shù)據(jù)類型），SpringFox 生成的 JSON 文件完全遵循此規(guī)范，確保與其他 Swagger 工具（如Swagger Editor）兼容

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

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

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

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

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

正式發(fā)布

最小化配置使用

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

第一步：引入Jar包

     

 org.springdoc groupId>     

 springdoc-openapi-starter-webmvc-ui artifactId>     

 2.5.0 version>  dependency>

第二步：配置配置文件

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

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

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

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

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

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

不加注解：

@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 = "參數(shù)1", required = true) String str1) {         return "請求成功";     } }

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

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

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

接下來開始進(jìn)行詳細(xì)配置：

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

@Configuration @OpenAPIDefinition(info = @Info(         title = "項目API文檔",         version = "1.0",         description = "SpringBoot項目接口文檔" )) publicclassSpringDocConfig {     /**      * 商品分組的配置（使用請求路徑掃描的方式進(jìn)行配置）      * @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();     }     /**      * 會員分組的配置（使用包掃描的方式進(jìn)行配置）      * @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會尋找環(huán)境中是否存在GroupedOpenApi類型的Bean，如果存在，則會創(chuàng)建分組進(jìn)行展示

注意：

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

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

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

以下展示我的代碼結(jié)構(gòu)，方便大家理解：

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

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

@Configuration @OpenAPIDefinition(info = @Info(         title = "項目API文檔",         version = "1.0",         description = "SpringBoot項目接口文檔" )) publicclassSpringDocConfig {     /**      * 默認(rèn)分組      * @return org.springdoc.core.models.GroupedOpenApi      * @author ren      * @date 2025/07/06 17:38      */     @Bean     public GroupedOpenApi defaultGroup() {         return GroupedOpenApi.builder()                 .group("默認(rèn)分組")                 .pathsToMatch("/**")   // 路徑匹配                 .build();     }     /**      * 商品分組的配置（使用請求路徑掃描的方式進(jìn)行配置）      * @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();     }     /**      * 會員分組的配置（使用包掃描的方式進(jìn)行配置）      * @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();     } }

配置后展示的內(nèi)容

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

方式二：聲明式配置（配置集中管理、可使用多配置文件進(jìn)行環(huán)境隔離）

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

如上：效果與方式一相同

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

WebMvcConfigurer

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

他所擁有的方法

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

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

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

• ?addViewControllers(registry)：設(shè)置簡易頁面跳轉(zhuǎn)

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

• ?configurePathMatch(configurer)：調(diào)整URL匹配規(guī)則

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

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

• ?configureContentNegotiation(configurer)：內(nèi)容協(xié)商配置（響應(yīng)格式協(xié)商）

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

@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());     } }

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

如果項目引入了SpringSecurity需要進(jìn)行的處理

由于項目引入了SpringSecurity，導(dǎo)致如果項目不經(jīng)過認(rèn)證無法訪問系統(tǒng)資源，我們就需要在SpringSecurity的配置文件中放開SpringDoc相關(guān)的靜態(tài)資源的攔截，如下

@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()                 // 靜態(tài)資源，可匿名訪問                 .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()                 // 除上面外的所有請求全部需要鑒權(quán)認(rèn)證                 .anyRequest().authenticated()         );         return http.build();     } }

添加如上配置后，即可放開SpringSecurity的認(rèn)證限制

總結(jié)

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

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

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

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

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

文章有幫助的話，點在看，轉(zhuǎn)發(fā)吧！