甩掉 Swagger UI！SpringBoot API 文檔神器強(qiáng)勢登場
在現(xiàn)代后端開發(fā)中，API 文檔已經(jīng)成為項目協(xié)作的基石——它不僅幫助前后端快速對接，也能為運(yùn)維、測試提供可靠的接口依據(jù)。過去，我們在 Spring Boot 項目中常用 Swagger + SpringFox 來生成交互式文檔，但隨著 Spring 版本的升級，這一套組合逐漸顯露疲態(tài)：維護(hù)停滯、版本不兼容、配置繁瑣…… 如果你還在為升級 Spring Boot 后 Swagger 失效而抓狂，那么今天介紹的 SpringDoc，將是你值得關(guān)注的下一代方案——它能在 Spring Boot 3.x + JDK17 環(huán)境下穩(wěn)定運(yùn)行，原生支持 OpenAPI 3 規(guī)范，并且實現(xiàn)了“零配置開箱即用”。
SpringDoc 是什么
SpringDoc 是一款專為 Spring Boot 應(yīng)用打造的 API 文檔生成工具，它會自動掃描項目中的：
- 控制器類（
@RestController） - 請求映射（
@RequestMapping、@GetMapping等） - OpenAPI 3 注解（
@Schema、@Parameter等）
然后動態(tài)生成 JSON / YAML / HTML 格式的 API 規(guī)范文件，并集成交互式的 Swagger UI 頁面，讓開發(fā)者直接在瀏覽器中調(diào)試接口。
核心能力：
- 自動掃描項目 API，無需手寫文檔
- 支持最新 OpenAPI 3 規(guī)范
- 集成 Swagger UI，可直接在線調(diào)試
- 與 Spring Boot 3.x 完美兼容
它與 Swagger 的關(guān)系
要理解 SpringDoc 的優(yōu)勢，我們先簡單回顧 Swagger 的角色。
- Swagger 是 OpenAPI 規(guī)范的前身，負(fù)責(zé)推動 API 描述標(biāo)準(zhǔn)化
- Swagger UI 是它的可視化工具，用于渲染交互式文檔
- SpringFox 曾是 Spring 生態(tài)中連接 Swagger 的橋梁，負(fù)責(zé)掃描代碼并生成 JSON 格式的 OpenAPI 文檔
在 2020 年以后，SpringFox 停止更新，并且在 Spring Boot 2.6+ / 3.x 中出現(xiàn)大量不兼容問題，比如：
- 路徑匹配失效
- 注解沖突
- 配置異常復(fù)雜
于是，SpringDoc 成為了替代者：它直接基于 OpenAPI 3 實現(xiàn)，無需依賴 SpringFox，并且保留了 Swagger UI 的可視化體驗。
為什么選擇 SpringDoc
選擇 SpringDoc 的理由非常直接：
- 官方持續(xù)維護(hù)：兼容 Spring Boot 最新版本
- 配置簡單：引入依賴即可運(yùn)行
- 原生 OpenAPI 3 支持：使用 JSR-303 注解替代 Swagger 專用注解
- 零侵入性：不破壞原有代碼結(jié)構(gòu)
- 性能穩(wěn)定：加載速度快，資源占用低
最小化集成步驟
引入依賴
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.5.0</version>
</dependency>可選配置（application.yml）
springdoc:
packages-to-scan: com.icoderoad.controller
swagger-ui:
enabled: true
path: /swagger-ui/index.html
url: /v3/api-docs
disable-swagger-default-url: false
api-docs:
enabled: true
path: /api-docs如果不配置，SpringDoc 會自動掃描全項目的 Controller 類。
基礎(chǔ)信息配置類
package com.icoderoad.config;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;
@Configuration
@OpenAPIDefinition(
info = @Info(title = "項目 API 文檔", version = "1.0", description = "SpringBoot 項目接口文檔")
)
public class SpringDocConfig {
}添加注解展示 API 信息
package com.icoderoad.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/main")
@Tag(name = "演示Controller", description = "演示接口")
public class MainController {
@GetMapping("/index")
@Operation(summary = "演示方法", description = "接口功能說明")
public String index(@Parameter(description = "參數(shù)1", required = true) String str1) {
return "請求成功";
}
}訪問地址：
http://localhost:8080/swagger-ui/index.html分組配置
編程式分組
package com.icoderoad.config;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SpringDocGroupConfig {
@Bean
public GroupedOpenApi defaultGroup() {
return GroupedOpenApi.builder().group("默認(rèn)分組").pathsToMatch("/**").build();
}
@Bean
public GroupedOpenApi productGroup() {
return GroupedOpenApi.builder().group("商品模塊").pathsToMatch("/api/product/**").build();
}
@Bean
public GroupedOpenApi userGroup() {
return GroupedOpenApi.builder().group("用戶模塊").packagesToScan("com.icoderoad.controller.member").build();
}
}聲明式分組（application.yml）
springdoc:
group-configs:
- group: 默認(rèn)分組
paths-to-match: "/**"
- group: 商品模塊
paths-to-match: "/api/product/**"
- group: 用戶模塊
packages-to-scan: "com.icoderoad.controller.member"特殊場景處理
WebMvcConfigurer 重寫資源映射
package com.icoderoad.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.*;
import java.util.concurrent.TimeUnit;
@Configuration
public class ResourcesConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/swagger-ui/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
.setCacheControl(org.springframework.http.CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());
}
}Spring Security 放行配置
package com.icoderoad.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.*;
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(auth -> auth
.requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
.requestMatchers("/swagger-ui/**", "/*/api-docs/**", "/swagger-resources/**", "/webjars/**").permitAll()
.anyRequest().authenticated()
);
return http.build();
}
}總結(jié)
過去的 Swagger + SpringFox 方案，在新版本 Spring Boot 中已經(jīng)力不從心；而 SpringDoc 作為 OpenAPI 3 的原生實現(xiàn)，不僅穩(wěn)定高效，還能通過最小化配置快速上手，滿足中大型項目的 API 文檔管理需求。 如果你想在 Spring Boot 3.x + JDK17+ 環(huán)境下?lián)碛幸粋€即插即用、可擴(kuò)展的 API 文檔工具，那么 SpringDoc 將是你不容錯過的選擇。它讓文檔與代碼同步更新，讓前后端協(xié)作更加流暢，讓 API 開發(fā)更具現(xiàn)代感。
