在前后端分離和微服務盛行的今天，API 文檔是團隊協作的“通用語言”。一份清晰、準確、實時同步的文檔，能極大提升開發和聯調效率。然而，手動編寫和維護 API 文檔（如 Word、Markdown 或 Postman）是一場永無止境的噩夢——它總是滯后于代碼的變更。

曾經，Springfox (Swagger 2) 是這個領域的王者，但隨著 Spring Boot 3.x 的到來，它已廉頗老矣。現在，SpringDoc OpenAPI?憑借其與 Spring Boot 的無縫集成和對 OpenAPI 3 規范的全面支持，成為了當之無愧的“終極解決方案”。

本文將帶你從零開始，深入探索 SpringDoc 的使用，從快速集成到精細化定制，讓你徹底告別手寫文檔的痛苦。

1. 為什么選擇 SpringDoc？

在2025年的今天，對于任何新的 Spring Boot 項目，選擇 SpringDoc 而非其前輩 Springfox 的理由非常充分：

• ??無縫集成 Spring Boot 3.x:?SpringDoc 是為現代 Spring Boot 版本量身打造的，能完美兼容 Spring Framework 6.x 和 Jakarta EE 9+。

• ??支持 OpenAPI 3 規范:?OpenAPI 3 是 API 描述的最新行業標準，提供了更豐富、更強大的規范定義能力。

• ??自動化程度高:?無需繁瑣的注解（如?@Api、@ApiModel），SpringDoc 能自動從你的 Spring Web 注解中推斷出大量信息。

• ??社區活躍:?項目正在積極開發和維護，能快速響應社區問題并跟進 Spring Boot 的更新。

2. 快速上手：三步集成交互式 API 文檔

在 Spring Boot 項目中集成 SpringDoc 極其簡單，真正做到了“開箱即用”。

第一步：添加依賴 (Maven)

只需在你的?pom.xml?中添加一個依賴即可。

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version>?</dependency>

如果你使用 WebFlux，請將?webmvc?替換為?webflux。

第二步：運行你的 Spring Boot 應用

沒錯，就是這樣。你不需要添加任何額外的注解或配置類，只需正常啟動你的應用。

第三步：訪問 API 文檔

啟動成功后，打開瀏覽器訪問以下兩個地址：

1. 1.?交互式 UI 界面:?http://localhost:8080/swagger-ui.html

2. 2.?OpenAPI 規范 (JSON格式):?http://localhost:8080/v3/api-docs

你會看到一個由 Swagger UI 提供的、功能齊全的交互式文檔頁面。它已經自動掃描了你項目中所有的?@RestController，并將其API展示了出來。

(這是一個示例圖片鏈接，實際效果類似)

3. 用注解“精雕細琢”你的 API 文檔

自動生成的基礎文檔雖然可用，但缺少描述、示例等關鍵信息。為了讓文檔更專業、更易于理解，我們需要使用 OpenAPI 3 的注解來“精雕細琢”。

核心注解:

• ??@Tag: 用于為 Controller 進行分組和描述。

• ??@Operation: 用于描述一個具體的 API 操作（方法）。

• ??@Parameter: 用于描述一個方法的參數。

• ??@Schema: 用于描述一個模型（DTO/VO）或其屬性。

• ??@ApiResponses?/?@ApiResponse: 用于描述可能的響應狀態和內容。

實戰示例：

UserDTO.java (數據傳輸對象)

import?io.swagger.v3.oas.annotations.media.Schema;// 使用 @Schema 描述整個類
@Schema(description = "用戶視圖對象")
public?class?UserDTO?{@Schema(description = "用戶ID", example = "1001")private?Long id;@Schema(description = "用戶名", requiredMode = Schema.RequiredMode.REQUIRED, example = "Alice")private?String username;// ... Getters and Setters
}

UserController.java (控制器)

import?io.swagger.v3.oas.annotations.Operation;
import?io.swagger.v3.oas.annotations.Parameter;
import?io.swagger.v3.oas.annotations.responses.ApiResponse;
import?io.swagger.v3.oas.annotations.responses.ApiResponses;
import?io.swagger.v3.oas.annotations.tags.Tag;
import?org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api/users")
// 使用 @Tag 為整個 Controller 分組
@Tag(name = "用戶管理", description = "提供用戶的增刪改查功能")
public?class?UserController?{@GetMapping("/{id}")// 使用 @Operation 描述方法@Operation(summary = "根據ID獲取用戶", description = "傳入用戶ID，返回單個用戶信息")// 使用 @Parameter 描述參數@Parameter(name = "id", description = "用戶ID", required = true, example = "1001")// 使用 @ApiResponses 描述所有可能的響應@ApiResponses({@ApiResponse(responseCode = "200", description = "成功找到用戶"),@ApiResponse(responseCode = "404", description = "用戶未找到")})public?UserDTO?getUserById(@PathVariable?Long id)?{// ... 業務邏輯 ...return?new?UserDTO(id,?"Alice");}@PostMapping@Operation(summary = "創建新用戶")public?UserDTO?createUser(@RequestBody?UserDTO user)?{// ... 業務邏輯 ...return?user;}
}

添加這些注解后，再次刷新?swagger-ui.html，你會發現文檔變得極其清晰、專業，包含了分組、描述、示例值和所有可能的響應碼。

4. 全局配置：打造專業的 API 門戶

除了針對單個 API 的注解，我們還需要配置文檔的全局信息，如標題、版本、聯系人、安全認證方案等。推薦使用定義?OpenAPI?Bean 的方式，因為它最靈活。

在任意?@Configuration?類中添加以下 Bean：

import?io.swagger.v3.oas.models.Components;
import?io.swagger.v3.oas.models.OpenAPI;
import?io.swagger.v3.oas.models.info.Info;
import?io.swagger.v3.oas.models.security.SecurityRequirement;
import?io.swagger.v3.oas.models.security.SecurityScheme;
import?org.springframework.context.annotation.Bean;
import?org.springframework.context.annotation.Configuration;@Configuration
public?class?OpenApiConfig?{@Beanpublic?OpenAPI?customOpenAPI()?{// 定義 JWT Bearer 認證方案final?String?securitySchemeName?=?"bearerAuth";return?new?OpenAPI()// 1. 定義全局信息.info(new?Info().title("我的應用 API").description("這是一個強大應用的 API 文檔").version("v1.0.0"))// 2. 添加全局安全認證需求.addSecurityItem(new?SecurityRequirement().addList(securitySchemeName))// 3. 在 Components 中定義安全認證方案的細節.components(new?Components().addSecuritySchemes(securitySchemeName,new?SecurityScheme().name(securitySchemeName).type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));}
}

配置此 Bean 后，Swagger UI 的右上角會出現一個“Authorize”按鈕，允許開發者輸入 JWT Token，從而方便地測試需要認證的接口。

5. 進階技巧與最佳實踐

• ??接口分組 (GroupedOpenApi): 如果你想為不同的 API 集合（如“對內API”和“對外API”）生成不同的文檔，可以定義多個?GroupedOpenApi?類型的 Bean。

• ??保護文檔端點: 在生產環境中，API 文檔不應公開訪問。你需要使用 Spring Security 來保護?/swagger-ui.html?和?/v3/api-docs?等相關路徑，只允許特定角色的用戶訪問。

• ??利用校驗注解: SpringDoc 會自動識別 JSR 303 / Jakarta Bean Validation 的注解（如?@NotNull,?@Size,?@Pattern），并將這些校驗規則展示在文檔中，這是非常有用的特性。

總結

在現代 Spring Boot 項目中，SpringDoc OpenAPI 已經不再是一個“錦上添花”的工具，而是保障團隊高效協作、提升項目專業度的核心基礎設施。