12.SpringDoc OpenAPI 功能介紹(用于生成API接口文檔)

SpringDoc OpenAPI 是一個基于 OpenAPI 3.0/3.1 規范的工具，用于為 Spring Boot 應用生成 API 文檔。它是 springfox（Swagger 2.x）的現代替代方案，完全支持 Spring Boot 3.x 和 JDK 17+，具有更強的兼容性和功能。

---

1. SpringDoc OpenAPI 核心概念

(1) OpenAPI 規范

• OpenAPI（原 Swagger 規范）是描述 RESTful API 的行業標準，支持 API 文檔、測試和客戶端代碼生成。
• SpringDoc OpenAPI 自動將 Spring Boot 的控制器、模型等轉換為 OpenAPI 格式，并生成交互式 UI（Swagger UI）。

(2) 與 Spring Boot 的集成

• 自動掃描：無需手動配置，SpringDoc 會自動掃描 @RestController、@RequestMapping 等注解的 API。
• 注解支持：通過 @Operation、@Tag 等注解豐富文檔內容。
• 支持現代技術棧：兼容 WebFlux、Kotlin、Jakarta EE 9+ 等。

(3) 關鍵組件

• OpenAPI 對象：定義 API 的元信息（標題、描述、版本等）。
• @Tag 注解：對 API 進行分類（如用戶管理、訂單管理）。
• @Operation 注解：描述單個 API 操作（如 GET、POST）。
• @Schema 注解：描述模型類的字段（如用戶 ID、用戶名）。

---

2. SpringDoc OpenAPI 核心知識點

(1) 依賴與版本

• Maven 依賴：

  <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version> <!-- 最新穩定版 -->
  </dependency>
  

• 版本選擇：
  • 2.x 系列支持 Spring Boot 3.x 和 OpenAPI 3.0。
  • 如果需要 OpenAPI 3.1，可以使用 springdoc-openapi-starter-webmvc-api。

(2) 配置方式

• 自動配置：
  • 默認配置下，SpringDoc 會自動生成 API 文檔，無需額外代碼。
• 自定義配置：
  • 通過 OpenAPI 對象自定義元信息（如標題、描述）。
  • 通過 @Tag 和 @Operation 注解補充 API 細節。

(3) 常用注解

注解	作用
@Tag	對 API 進行分類（如 @Tag(name = "用戶管理")）。
@Operation	描述單個 API 操作（如 @Operation(summary = "獲取用戶")）。
@Schema	描述模型類的字段（如 @Schema(description = "用戶ID")）。
@Parameter	描述請求參數（如 @Parameter(description = "用戶ID")）。
@ApiResponse	描述響應狀態碼和內容（如 @ApiResponse(responseCode = "200")）。

(4) 執行路徑

• Swagger UI 路徑：
  • 默認訪問：http://localhost:8080/swagger-ui.html。
  • 可通過配置修改路徑：

    @Bean
    public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/public/**").build();
    }
    

• OpenAPI JSON 路徑：
  • 默認訪問：http://localhost:8080/v3/api-docs。
  • 支持分組 API 的 JSON 路徑（如 /v3/api-docs/public）。

---

3. SpringDoc OpenAPI 的工作流程

1. 啟動應用：
   • SpringDoc 自動掃描所有 @RestController 和 @RequestMapping 注解的 API。
2. 生成文檔：
   • 根據控制器、模型和注解生成 OpenAPI 3.0/3.1 格式的 JSON。
3. 渲染 UI：
   • 通過 Swagger UI 渲染交互式文檔，支持測試 API。

---

4. 高級功能

(1) 分組 API

• 將 API 按功能分組（如公共 API、管理員 API）：

  @Bean
  public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/public/**").build();
  }
  

• 訪問分組后的 Swagger UI：
  • http://localhost:8080/swagger-ui/index.html#/public

(2) 安全性集成

• 如果項目啟用了 Spring Security，需要允許訪問 Swagger UI：

  @Configuration
  public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/swagger-ui.html", "/v3/api-docs/**").permitAll().anyRequest().authenticated();}
  }
  

(3) 自定義 UI 配置

• 修改 Swagger UI 的標題、布局等：

  @Bean
  public UIConfiguration uiConfig() {return UIConfiguration.builder().deepLinking(true).displayOperationId(false).docExpansion(DocExpansion.NONE).build();
  }
  

(4) 支持 OpenAPI 3.1

• 使用 springdoc-openapi-starter-webmvc-api 依賴：

  <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId><version>2.3.0</version>
  </dependency>
  

---

5. 與 Spring Boot 3.x 的兼容性

• 為什么不用 springfox？
  • springfox（Swagger 2.x）依賴了已移除的 Spring MVC 組件（如 PathPatternParser），無法與 Spring Boot 3.x 兼容。
  • SpringDoc OpenAPI 是專門為 Spring Boot 3.x 和 Jakarta EE 9+ 設計的。

---

6. 總結

• 優勢：
  • 完全兼容 Spring Boot 3.x 和 JDK 17+。
  • 支持 OpenAPI 3.0/3.1，功能更強大。
  • 無需手動配置，自動掃描 API。
• 適用場景：
  • 需要快速生成 API 文檔的 Spring Boot 項目。
  • 需要支持 OpenAPI 3.0/3.1 的現代應用。
• 對比 springfox：
  • SpringDoc 是 springfox 的替代方案，推薦在新項目中使用。

通過 SpringDoc OpenAPI，可以輕松為 Spring Boot 應用生成高質量的 API 文檔，并支持交互式測試。