Swagger @Parameter 與 @Schema

1. 概述

在本教程中，我們將簡要了解一下 Swagger 的@Parameter和@Schema註解。此外，我們將比較這些註釋並確定每個註釋的正確用法。

2. 主要區別

簡單來說, @Parameter和@Schema註解為Swagger添加了不同的元數據。 @Parameter註解用於API資源請求的參數，而@Schema用於模型的屬性。

3. @Parameter

@Parameter註釋用於定義操作或路徑的參數部分中的參數。 @Parameter註釋有助於指定參數的名稱、描述和示例值。此外，我們可以指定參數是必需的還是可選的。

我們看一下它的用法：

@RequestMapping(
 method = RequestMethod.POST,
 value = "/createUser",
 produces = "application/json; charset=UTF-8")
 @ResponseStatus(HttpStatus.CREATED)
 @ResponseBody
 @Operation(summary = "Create user",
 description = "This method creates a new user")
 public User createUser(@Parameter(
 name = "firstName",
 description = "First Name of the user",
 example = "Vatsal",
 required = true)
 @RequestParam String firstName) {
 User user = new User(firstName);
 return user;
 }

讓我們看一下@Parameter示例的Swagger UI表示：

現在，讓我們看看@Schema 。

4. @Schema

@Schema註釋允許我們控制特定於 Swagger 的定義，例如描述、名稱、類型、示例值和模型屬性的允許值。

此外，它還提供了額外的過濾屬性，以防我們想在某些情況下隱藏該屬性。

讓我們向User's firstName字段添加一些模型屬性：

@Schema(
 description = "first name of the user",
 name = "firstName",
 type = "string",
 example = "Vatsal")
 String firstName;

現在，我們來看看 Swagger UI 中User Model 的規範：

5. 結論

在這篇簡短的文章中，我們了解了兩個可用於添加參數和模型屬性元數據的 Swagger 註釋。然後，我們查看了一些使用這些註釋的示例代碼，並在 Swagger UI 中看到了它們的表示形式。

與往常一樣，所有這些代碼示例都可以在 GitHub 上獲取。