使用 Swagger 示例和描述

1. 概述

在本教程中，我們將演示如何使用 Swagger 註解來使我們的文檔更具描述性。首先，我們將學習如何為 API 的不同部分添加描述，例如方法、參數和錯誤代碼。然後，我們將看到如何添加請求/響應示例。

2. 項目設置

我們將創建一個簡單的 Products API，該 API 提供創建和獲取產品的各種方法。

為了從頭創建一個 REST API，我們可以遵循 Spring Docs 提供的此教程：使用 Spring Boot 創建 RESTful Web 服務。

下一步將是設置項目的依賴項和配置。您可以按照本文中的步驟設置 Swagger 2 與 Spring REST API 的集成。

3. 創建 API

讓我們創建我們的 Products API 並查看生成的文檔。

3.1. 模型

讓我們定義我們的產品類:

public class Product implements Serializable {
    private long id;
    private String name;
    private String price;

    // constructor and getter/setters
}

3.2. 控制器

讓我們定義兩個 API 方法：

@RestController
@Tag(name = "Products API")
public class ProductController {

    @PostMapping("/products")
    public ResponseEntity<Void> createProduct(@RequestBody Product product) {
        //creation logic
        return new ResponseEntity<>(HttpStatus.CREATED);
    }

    @GetMapping("/products/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable Long id) {
        //retrieval logic
        return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
    }
}

當我們運行項目時，該庫將讀取所有暴露的路徑並創建相應的文檔。

請在默認 URL http://localhost:8080/swagger-ui/index.html 中查看文檔：

我們可以進一步擴展控制器方法以查看其各自的文檔。接下來，我們將逐個詳細分析它們。

4. 使我們的文檔更具描述性

現在，讓我們通過為不同方法的各個部分添加描述，使我們的文檔更具描述性。

4.1. 為方法和參數添加描述

讓我們看看如何使方法更具描述性。我們將為方法、參數和響應代碼添加描述。我們先從 getProduct() 方法開始：

@Operation(summary = "Get a product by id", description = "Returns a product as per the id")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Successfully retrieved"), 
        @ApiResponse(responseCode = "404", description = "Not found - The product was not found")
    })
@GetMapping("/products/{id}")
public ResponseEntity<Product> getProduct(@PathVariable("id") @Parameter(name = "id", description = "Product id", example = "1") Long id) {
    //retrieval logic
    return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
}

@Operation 定義了 API 方法的屬性。我們使用value屬性為操作添加了名稱，並使用notes屬性添加了描述。

@ApiResponses 用於覆蓋默認與響應代碼相關的消息。對於我們想要更改的每個響應消息，都需要添加@ApiResponse對象。

例如，如果產品未找到，我們的 API 在這種情況下返回 HTTP 404 狀態碼。如果沒有添加自定義消息，原始消息“未找到”可能難以理解。調用者可能會將其解釋為 URL 不正確。但是，添加描述“產品未找到”會更清楚。

@Parameter 定義了方法參數的屬性。它可以與路徑、查詢、標題和表單參數一起使用。我們為“id”參數添加了名稱、值（描述）和示例。如果沒有添加自定義設置，庫只會獲取參數的名稱和類型，如第一張圖片所示。

讓我們看看這如何改變文檔：

在這裏，我們可以看到名稱“獲取產品 ID”與 API 路徑/products/{id} 旁邊的名稱。我們還可以看到其描述就在其下方。此外，在參數部分，我們有一個描述和“id”字段的示例。最後，在響應部分，我們可以看到 200 和 404 代碼的錯誤描述已更改。

4.2. 為模型添加描述和示例

我們可以對我們的 createProduct() 方法進行類似的改進。由於該方法接受一個 Product對象，因此在 Product類本身中提供描述和示例更合理。

讓我們對 Product類進行一些修改以實現這一點：

@Schema(name = "Product ID", example = "1", required = true)
private Long id;
@Schema(name = "Product name", example = "Product 1", required = false)
private String name;
@Schema(name = "Product price", example = "$100.00", required = true)
private String price;

@Schema 註解定義了字段的屬性。 我們使用該註解為每個字段設置其 name、example 和 required 屬性。

讓我們重啓應用程序，並再次查看我們的 Product 模型文檔：

如果我們將其與原始文檔圖像進行比較，我們會發現新圖像包含示例、描述和紅色星號(*)以標識必需的參數。

通過向模型添加示例，我們可以自動在每個使用模型作為輸入或輸出的方法中創建示例響應。 例如，從與 getProduct() 方法對應的圖像中，我們可以看到響應包含包含我們在模型中提供的相同值的示例。

向文檔添加示例很重要，因為這使得值格式更加精確。如果我們的模型包含諸如日期、時間或價格之類的字段，則需要精確的值格式。事先定義格式可以使 API 提供方和 API 客户端雙方都更有效地進行開發過程。

5. 結論

在本文中，我們探討了多種提高 API 文檔可讀性的方法。我們學習瞭如何使用註解 <em @Parameter, @Operation, @ApiResponses, @ApiResponse, @Schema</em> 來文檔化方法、參數、錯誤消息和模型。

知識庫 / Spring RSS 訂閱