在現代企業級應用開發中，前后端分離已成為主流模式，前端負責界面呈現，后端專注提供 RESTful API 接口。然而，接口文檔的編寫和維護往往是開發過程中的痛點。Spring Boot 3.4.3 結合 SpringDoc 2 和 Swagger 3，為開發者提供了一種高效的方式，通過 OpenAPI 3 標準自動生成和管理接口文檔。本文將詳細介紹如何在 Spring Boot 3.4.3 中集成 SpringDoc 2 和 Swagger 3，構建標準化的接口文檔，并附上完整的代碼示例和單元測試指南。

---

1. SpringDoc 和 Swagger 簡介

1.1 什么是 SpringDoc？

SpringDoc 是一個開源庫，專為 Spring 框架設計，用于根據項目代碼自動生成符合 OpenAPI 3.0 規范的 API 文檔。它通過掃描控制器和注解，生成詳細的接口信息，幫助開發者輕松創建和維護 RESTful API 文檔。

1.2 Swagger 的作用

Swagger 是一個廣受歡迎的 API 文檔工具，Swagger 3 基于 OpenAPI 3.0 標準，提供可視化的接口文檔界面（Swagger UI），支持在線查看和測試 API。SpringDoc 將 Swagger 的功能集成到 Spring 項目中，簡化了配置流程。

1.3 優點

• 自動化：無需手動編寫文檔，減少維護成本。
• 標準化：遵循 OpenAPI 3.0，提供一致的文檔格式。
• 交互性：Swagger UI 支持在線調試 API，提升開發效率。

---

2. 使用場景

SpringDoc 和 Swagger 適用于以下場景：

• 前后端分離：為前端提供清晰的接口說明。
• 團隊協作：確保開發者和測試人員快速理解 API。
• 微服務架構：管理多個服務的接口文檔。
• 快速迭代：接口變更時自動更新文檔。

---

3. 項目實戰

以下是基于 Spring Boot 3.4.3 集成 SpringDoc 2 和 Swagger 3 的完整步驟。

3.1 添加 Maven 依賴

在 pom.xml 中添加必要的依賴：

<dependencies><!-- Spring Boot Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- SpringDoc OpenAPI --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.0.2</version></dependency><!-- 測試支持 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
</dependencies>

說明：

• springdoc-openapi-starter-webmvc-ui 集成了 Swagger UI 和 OpenAPI 3 支持。
• Spring Boot 3.4.3 默認使用 Jakarta EE，無需額外處理兼容性問題。

3.2 創建 RESTful 接口

創建一個簡單的控制器示例：

package cn.joyous.controller;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api")
@Tag(name = "用戶管理", description = "用戶相關操作接口")
public class UserController {@Operation(summary = "獲取用戶信息", description = "根據用戶ID獲取詳細信息")@GetMapping("/user/{id}")public String getUser(@PathVariable("id") Long id) {return "User ID: " + id;}@Operation(summary = "創建用戶", description = "新增一個用戶")@PostMapping("/user")public String createUser(@RequestParam("name") String name) {return "User created: " + name;}
}

注解說明：

• @Tag：定義接口分組。
• @Operation：描述接口的功能和詳情。
• SpringDoc 會根據這些注解生成文檔。

3.3 配置 SpringDoc（可選）

SpringDoc 默認無需額外配置即可使用 Swagger UI。如果需要自定義文檔信息，可以添加配置類：

package cn.joyous.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Spring Boot 3.4.3 API 文檔").version("1.0.0").description("基于 SpringDoc 2 和 Swagger 3 的接口文檔示例"));}
}

3.4 啟動與訪問

1. 啟動 Spring Boot 應用（默認端口 8080）。
2. 訪問 Swagger UI：http://localhost:8080/swagger-ui/index.html。
3. 你將看到自動生成的接口文檔，包括 /api/user/{id} 和 /api/user 兩個接口，支持在線測試。

---

4. 單元測試

為確保接口文檔和功能正常運行，可以編寫單元測試。

4.1 測試依賴

確保 pom.xml 已包含 spring-boot-starter-test。

4.2 測試代碼

創建一個測試類：

package cn.joyous.controller;import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;@SpringBootTest
@AutoConfigureMockMvc
public class UserControllerTest {@Autowiredprivate MockMvc mockMvc;@Testpublic void testGetUser() throws Exception {mockMvc.perform(get("/api/user/1")).andExpect(status().isOk()).andExpect(content().string("User ID: 1"));}
}

說明：

• @SpringBootTest：加載 Spring 上下文。
• @AutoConfigureMockMvc：啟用 MockMvc 用于模擬 HTTP 請求。
• 測試驗證了 /api/user/{id} 接口的正確性。

4.3 運行測試

在 IDE 中運行測試，確保接口返回預期結果。

---

5. 進階配置（可選）

1. 多環境支持
   在 SpringDocConfig 中配置不同環境的服務器地址：

   import io.swagger.v3.oas.models.servers.Server;@Bean
   public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文檔").version("1.0.0")).addServersItem(new Server().url("http://localhost:8080").description("開發環境")).addServersItem(new Server().url("https://api.example.com").description("生產環境"));
   }
   

2. 分組接口
   使用 @Tag 或 SpringDoc 的分組功能分隔不同模塊的接口：

   @Bean
   public GroupedOpenApi userApi() {return GroupedOpenApi.builder().group("user-api").pathsToMatch("/api/user/**").build();
   }
   

3. 安全性集成
   若項目使用 Spring Security，可添加認證支持：

   @Bean
   public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文檔")).addSecurityItem(new SecurityRequirement().addList("bearerAuth")).components(new Components().addSecuritySchemes("bearerAuth",new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
   }
   

---

6. 總結

Spring Boot 3.4.3 結合 SpringDoc 2 和 Swagger 3，為接口文檔管理提供了一套高效、標準化的解決方案。通過簡單的依賴引入和少量配置，你可以快速生成交互式的 API 文檔，極大提升開發效率和團隊協作能力。本文從基礎集成到單元測試，再到進階配置，涵蓋了完整實踐過程，希望對你有所幫助。