SpringDoc：Spring Boot 應用 API 文檔生成的現代化解決方案
概述
SpringDoc 是一個專為 Spring Boot 應用設計的開源庫，能夠自動生成符合 OpenAPI 3 規范的 API 文檔。它通過掃描項目中的控制器、方法注解及相關配置，動態生成 JSON/YAML/HTML 格式的文檔，并提供 Swagger UI 等交互式界面供開發者查看和測試 API。
與 Swagger 的關系
Swagger 作為 OpenAPI 規范的前身，貢獻了 API 設計理念并推動了 OpenAPI 的標準化進程，其核心工具 Swagger UI 用于展示交互式文檔。需要明確的是：
- SpringDoc 不是 Swagger 的替代品，而是基于 OpenAPI 3 規范的實現工具
- SpringDoc 天然集成 Swagger UI 作為文檔展示界面
- 它使用現代 JSR-303 規范注解，替代了傳統 Swagger 專屬注解
為什么選擇 SpringDoc
SpringFox 的衰落
在 SpringDoc 面世之前，Spring 生態中主要使用 SpringFox 實現 Swagger 集成：
SpringFox 工作機制：
- 運行時掃描 Spring MVC 控制器（如
@RestController）、方法注解（如@RequestMapping）及 Swagger 專用注解 - 提取接口的路徑、參數、響應等信息
- 生成符合 Swagger 2.0 或 OpenAPI 3.0 規范的 JSON 文件
- 集成 Spring 生態，提供 Docket 配置類支持自定義配置
Swagger UI 作用：
- 將 SpringFox 生成的 JSON 文件解析為交互式網頁
- 提供接口列表、參數說明、請求示例和在線測試功能
- 確保與其他 Swagger 工具兼容
協作流程：
- 開發階段：開發者在控制器中添加 Swagger 注解描述接口細節
- 運行時：SpringFox 掃描代碼并生成 JSON 文檔
- 展示階段：Swagger UI 讀取 JSON 文件并渲染可視化界面
SpringDoc 的優勢
自 2020 年起，SpringFox 官方基本停止維護，導致：
- 無法適配 Spring Boot 2.6+ 及 3.x 版本
- 與新版本 Spring 生態沖突（路徑匹配失效、注解不兼容）
- 配置復雜性問題
SpringDoc 作為新一代解決方案具有以下優勢：
- 完美支持 Spring Boot 2.6+ 及 3.x（含 JDK 17+）
- 原生支持 OpenAPI 3 規范
- 零配置開箱即用（僅需引入一個依賴）
- 使用 JSR-303 規范注解（如
@Schema、@Parameter），降低學習成本
最小化配置使用
第一步：引入依賴
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version><!-- 建議使用最新版本 -->
</dependency>
第二步：配置文件說明（可選）
# application.yml
springdoc:# API 包掃描路徑（不配置則自動掃描整個項目）packages-to-scan: com.example.controllerswagger-ui:enabled: true # 是否開啟 Swagger 界面path: /swagger-ui/index.html # 訪問路徑url: /v3/api-docs # 指定 OpenAPI 文檔 URLdisable-swagger-default-url: false # 是否禁用自帶示例接口api-docs:enabled: true # 啟用 OpenAPI 文檔端點path: /api-docs # 文檔訪問路徑
第三步：基礎配置類
@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 "請求成功";}
}
界面顯示效果：僅顯示基礎路徑和參數信息，缺少詳細描述。
添加注解的 Controller：
@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 "請求成功";}
}
界面顯示效果：包含完整的模塊描述、方法說明和參數說明。
注意：以上配置生效前提是項目未添加過濾器、攔截器或 Spring Security 等安全框架，否則需要額外配置。
分組配置
SpringDoc 支持靈活的 API 分組展示功能。
編程式配置（推薦）
@Configuration
@OpenAPIDefinition(info = @Info(title = "項目API文檔",version = "1.0",description = "SpringBoot項目接口文檔"
))
public class SpringDocConfig {// 默認分組（包含所有接口）@Beanpublic GroupedOpenApi defaultGroup() {return GroupedOpenApi.builder().group("默認分組").pathsToMatch("/**").build();}// 商品模塊分組（路徑匹配方式）@Beanpublic GroupedOpenApi productGroup() {return GroupedOpenApi.builder().group("商品模塊").pathsToMatch("/api/product/**").build();}// 用戶模塊分組（包掃描方式）@Beanpublic GroupedOpenApi userGroup() {return GroupedOpenApi.builder().group("用戶模塊").packagesToScan("com.example.controller.user").build();}
}
聲明式配置
springdoc:group-configs:- group: '默認分組'paths-to-match: '/**'- group: '商品模塊'paths-to-match: '/api/product/**'- group: '用戶模塊'packages-to-scan: 'com.example.controller.user'
注意事項
- 分組配置優先級高于配置文件中的
packages-to-scan配置 - 支持路徑匹配和包掃描兩種方式
- 同一接口可同時存在于多個分組中
- 如不配置默認分組，未匹配的接口將不會顯示
常見問題處理
重寫 WebMvcConfigurer 時的處理
如果項目重寫了 addResourceHandlers 方法，需要手動添加 SpringDoc 資源映射：
@Configuration
public class ResourcesConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/").setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());}
}
集成 Spring Security 時的處理
需要在 Security 配置中放開相關資源的訪問權限：
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeHttpRequests(auth -> auth.requestMatchers(HttpMethod.OPTIONS, "/**").permitAll().requestMatchers(request -> {String path = 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/**").permitAll().anyRequest().authenticated());return http.build();}
}
我的項目結構：可參考
總結
SpringDoc 為 Spring Boot 應用提供了現代化、標準化的 API 文檔生成方案。相比傳統的 SpringFox，它具有更好的兼容性、更簡單的配置方式和更低的維護成本。通過本文介紹的配置方法和最佳實踐，開發者可以快速集成并定制符合項目需求的 API 文檔系統。
關鍵優勢總結：
- 開箱即用：最小配置即可快速上手
- 全面兼容：支持最新 Spring Boot 和 JDK 版本
- 靈活分組：支持多種方式的 API 分類管理
- 生態集成：無縫對接 Spring Security 等常用組件
- 規范標準：基于 OpenAPI 3 和 JSR-303 標準
通過合理運用 SpringDoc，團隊可以顯著提升 API 開發效率和文檔質量，促進前后端協作的順暢進行。
)
)
