• com.swaggertags">
• demo">

接下來，我們點擊 Generate 按鈕下載我們的項目。 下載項目包後，我們可以提取其內容。

接下來，讓我們為我們的項目配置添加所需的依賴項。

3.1. 添加 MavenDependencies

We need a controller to demo our grouping of resources。 所以，讓我們添加一個 web starter dependency:

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

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

現在，讓我們添加 Swagger dependency 以開始使用 Swagger：

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

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

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 控制器，這意味着它處理 HTTP 請求並以 RESTful 方式返回響應。 註解 @RequestMapping(“/api/users/”) 設置了控制器中所有方法的基 URL 路徑，有助於組織和分組相關的端點。

此外，註解 @Tag，該註解來自 SpringDoc (Swagger/OpenAPI) 庫，用於在生成的 Swagger 文檔中將相關的 API 端點分組。 註解 name (例如 “User Management“) 在 Swagger UI 中創建一個類別，而註解 description (例如 “Operations related to users“) 添加有用的上下文，使類別更易於理解。

我們還可以使用註解 @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，該 URL 代表 Swagger UI 的默認 URL。

我們看到兩個組以及它們中的相關端點，當我們展開它們時:

5. 結論

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

來自 @Tag 註解對於 Spring Boot 中的 API 組織至關重要。通過在類或方法級別應用 @Tag，我們可以將相關的端點（如用户和訂單操作）分組到 Swagger UI 中的可摺疊部分，從而提高可讀性、結構性和協作性。

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