按資源分組端點 - Swagger - REST,Swagger 知識庫詳情

1. 簡介

本教程將探討 Java 中 Swagger 文檔功能。具體來説，我們將重點關注如何基於 URL 對項目 API 進行組織。

有多種方法可以實現這種資源分組。然而，對於本次討論，我們將集中關注 @Tag 註解，該註解通常應用於控制器上。

2. 理解 Swagger 和 <em @Tag 註解

Swagger 是一個非常實用的開源框架，它幫助我們設計、構建、文檔和測試我們的 REST API。它的主要特點是自動生成，確保文檔始終保持與我們的 API 一致，並且始終保持最新狀態。

在 Swagger (OpenAPI) 的語境下，標籤作為一種關鍵機制，用於對我們的 API 操作進行分組和分類。它們提供了一種強大的方法來組織 API 文檔，從而提高其清晰度和可使用性。

重要的是要注意，標籤可以在我們的控制器類中的類或函數級別定義。 因此，無論是一個 GET、POST、PUT 還是 DELETE 請求，都可以與一個或多個標籤關聯。

此外，Swagger UI 通常會將這些標籤渲染為可摺疊部分或類別，從而實現輕鬆的導航和理解。

因此，通過有效地利用標籤，我們可以顯著提高 API 文檔的結構和可訪問性。

3. 設置 Spring Boot 項目

在開始使用 Swagger 之前，我們需要一個帶有 API 的 Spring Boot 項目。

為了開始，我們將導航到 Spring Initializer。隨後，我們將使用以下參數配置我們的項目：

項目： Maven
語言： Java
Spring Boot 版本： 3.4.4 (或任何穩定版本)
Group： com.swaggertags
Artifact： demo
描述： Swagger 標籤的演示項目
打包： Jar
JDK： 17

之後，我們點擊 Generate 按鈕下載我們的項目。下載項目歸檔文件後，我們可以提取其內容。

接下來，讓我們將必要的依賴項添加到項目配置文件的內容中。

3.1. 添加 Maven 依賴項

我們需要一個控制器來演示我們資源的組別。因此，我們添加一個 Web Starter 依賴項：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

它引入了創建 RESTful API、網頁和其他基於 Web 的功能的必要組件。

現在，讓我們添加 Swagger 依賴項以開始使用 Swagger：

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

此依賴項為我們的 Spring Boot Web MVC 應用程序添加了 Swagger/OpenAPI 支持，並提供了一個用户友好的界面。

4. 使用 Swagger 註解創建控制器類

讓我們創建一個 UserController，該類包含所有與用户相關的操作，URL 以 “/api/users/” 開頭：

@RestController @RequestMapping("/api/users/") @Tag(name = "User Management", description = "Operations related to users") public class UserController { @PostMapping("login") public ResponseEntity<String> userLogin() { return ResponseEntity.ok("Logged In"); } @Tag(name = "dashboard") @GetMapping("profile") public ResponseEntity<String> getUserProfile() { return ResponseEntity.ok("User Profile"); } @Tag(name = "dashboard") @GetMapping("orders") public ResponseEntity<String> getUserOrders() { return ResponseEntity.ok("User Orders"); } }
讓我們理解一下上方類定義的註釋。

@RestController 標註表明該類是一個 REST 控制器，這意味着它處理 HTTP 請求並以 RESTful 的方式返回響應。@RequestMapping(“/api/users/”) 標註設置控制器中所有方法的基 URL 路徑，有助於組織和分組相關的端點。

此外，@Tag 標註，來自 SpringDoc (Swagger/OpenAPI) 庫，用於在生成的 Swagger 文檔中將相關的 API 端點分組。name 屬性（例如，“用户管理”）創建一個 Swagger UI 中的類別，而description 屬性（例如，“與用户相關的操作”）則添加有用的上下文，使類別更易於理解。

我們還可以使用 @Tag 標註在單個方法上，例如 getUserOrders()，以對特定端點進行分類。

讓我們創建一個名為 OrderController 的控制器，其中包含所有與訂單相關的操作，並且這些 URL 以 “/api/orders” 開頭：

@RestController @RequestMapping("/api/orders") @Tag(name = "Order Management", description = "Operations related to orders") public class OrderController { @GetMapping public ResponseEntity<String> getAllOrders() { return ResponseEntity.ok("Order 1"); } }
再次，我們仍然擁有相同的 @Tag 註解，用於將具有相同前綴的相關 API 組在一起。但是，這次，名稱和描述不同，這會導致不同的組。

4.1. 輸出

現在我們可以運行我們的應用程序，並訪問 URL “http://localhost:8080/swagger-ui/index.html”，它代表 Swagger UI 的默認 URL。

展開後，我們可以在其中看到兩個組及其相關的端點。

5. 結論

在本文中，我們瞭解到 Swagger（現在是 OpenAPI 規範的一部分）是一個強大的工具，它簡化了 REST API 的設計、文檔和測試。它能夠自動生成實時、交互式的 API 文檔，從而減少手動工作並確保我們的文檔始終與代碼保持同步。

 註解來自 ，對於 Spring Boot 中的 API 組織至關重要。通過在類或方法級別應用 ，我們可以將相關的端點（例如用户和訂單操作）分組到 Swagger UI 中獨立的、可摺疊的區域中。這提高了可讀性、結構性和協作性，對開發者有益。

通過最小的設置（添加幾個 Maven 依賴項和控制器註解），我們就能獲得一個結構良好的 Swagger UI，其中我們的 API 明確分組且易於導航。這增強了開發人員的體驗，尤其是在大型應用程序中。

知識庫 / REST RSS 訂閱