在 Swagger 中按資源對端點進行分組
1. 簡介
在本教程中，我們將探索 Java 中的 Swagger 文件功能。具體來說，我們將重點放在如何根據 URL 來組織我們專案的 API。
有幾種方法可以實現這種資源分組。然而，在本次討論中，我們將集中討論@Tag註釋，它通常應用於我們的控制器之上。
2. 理解 Swagger 和@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（或任何穩定版本）
- 團體：
com.swaggertags - 工件：
demo - 描述：Swagger 標籤的示範項目
- 包裝：罐
- JDK：17
接下來，我們點擊Generate按鈕來下載我們的專案。一旦專案檔案下載完畢，我們就可以提取其內容。
接下來，讓我們將必要的依賴項新增到專案的設定檔中。
3.1.新增 Maven依賴項
我們需要一個控制器來示範我們的資源分組。因此，讓我們新增一個Web 啟動器相依性：
<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 @Tag註解建立控制器類
讓我們建立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註解告訴 Spring 該類別是一個 REST 控制器，這表示它以 RESTful 方式處理 HTTP 請求並回傳回應。 @RequestMapping(“/api/users/”)註解為控制器內的所有方法設定基本 URL 路徑，有助於組織和分組相關端點。
此外，來自 SpringDoc（Swagger/OpenAPI）庫的@Tag註釋用於在生成的 Swagger 文件中對相關的 API 端點進行分組。 name屬性（例如「 User Management 」）在 Swagger UI 中建立一個類別，而description屬性（例如「 Operations related to users 」）則添加有用的上下文以使類別更易於理解。
我們也可以在各個方法（例如getUserOrders()上使用@Tag註釋來對特定端點進行分類。
我們還建立一個名為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.輸出
現在我們可以執行我們的應用程式並前往代表預設 Swagger UI URL 的 URL “http://localhost:8080/swagger-ui/index.html” 。
隨著擴展，我們會看到兩組以及它們內部與它們相關的端點：
5. 結論
在本文中，我們了解了 Swagger（現在是 OpenAPI 規範的一部分）如何成為一個強大的工具，簡化 REST API 的設計、記錄和測試。它會自動產生即時、互動式 API 文檔，減少手動工作量並使我們的文檔始終與我們的程式碼保持同步。
springdoc-openapi中的@Tag註解對於 Spring Boot 中的 API 組織至關重要。透過在類別或方法層級套用@Tag ，我們可以將相關端點（例如使用者和訂單操作）分組到 Swagger UI 中不同的可折疊部分。這提高了開發人員的可讀性、結構和協作。
透過最少的設定（添加一些 Maven 依賴項和控制器註釋），我們得到了一個組織良好的 Swagger UI，其中我們的 API 分組清晰且易於導航。這增強了開發人員的體驗，特別是在較大的應用程式中。
與往常一樣，本文的程式碼可在 GitHub 上找到。