Swagger 中的 @ApiOperation 與 @ApiResponse

一、概述

在本教程中，我們將討論 Swagger 的@ApiOperation和@ApiResponse註釋之間的主要區別。

2. Swagger 的描述性文檔

當我們創建 REST API 時，創建適當的規範也很重要。此外，這樣的規範應該是可讀的、可理解的，並提供所有必要的信息。

此外，文檔應該包含對 API 所做的每項更改的描述。手動創建 REST API 文檔會很累，更重要的是，會很耗時。幸運的是，像 Swagger 這樣的工具可以幫助我們完成這個過程。

Swagger代表了一組圍繞 OpenAPI 規範構建的開源工具。它可以幫助我們設計、構建、記錄和使用 REST API。

Swagger 規範是記錄 REST API 的標準。使用 Swagger 規範，我們可以描述我們的整個 API，例如暴露的端點、操作、參數、身份驗證方法等。

Swagger 提供了各種註釋，可以幫助我們記錄 REST API。此外，它還提供了@ApiOperation和@ApiResponse註釋來記錄我們 REST API 的響應。在本教程的其餘部分，我們將使用以下控制器類並了解如何使用這些註釋：

@RestController
 @RequestMapping("/customers")
 class CustomerController {

 private final CustomerService customerService;

 public CustomerController(CustomerService customerService) {
 this.customerService = customerService;
 }

 @GetMapping("/{id}")
 public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
 return ResponseEntity.ok(customerService.getById(id));
 }
 }

3. @ApiOperation

@ApiOperation註解用於描述單個操作。操作是路徑和 HTTP 方法的唯一組合。

此外，使用@ApiOperation ，我們可以描述成功的 REST API 調用的結果。換句話說，我們可以使用這個註解來指定一般的返回類型。

讓我們將註解添加到我們的方法中：

@ApiOperation(value = "Gets customer by ID",
 response = CustomerResponse.class,
 notes = "Customer must exist")
 @GetMapping("/{id}")
 public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
 return ResponseEntity.ok(customerService.getById(id));
 }

接下來，我們將@ApiOperation中一些最常用的屬性。

3.1。 value屬性

必需的value屬性包含操作的匯總字段。簡而言之，它提供了操作的簡短描述。但是，我們應該將此參數保持在 120 個字符以內。

以下是我們在@ApiOperation註釋中定義 value 屬性的方式：

@ApiOperation(value = "Gets customer by ID")

3.2. notes屬性

使用notes ，我們可以提供有關操作的更多詳細信息。例如，我們可以放置一個描述端點限制的文本：

@ApiOperation(value = "Gets customer by ID", notes = "Customer must exist")

3.3. response屬性

response屬性包含操作的響應類型。此外，設置此屬性將覆蓋任何自動派生的數據類型。 @ApiOperation註解中定義的響應屬性應該包含通用響應類型。

讓我們創建一個類來代表我們的方法返回的成功響應：

class CustomerResponse {

 private Long id;
 private String firstName;
 private String lastName;

 // getters and setters
 }

接下來，讓我們將response屬性添加到我們的註解中：

@ApiOperation(value = "Gets customer by ID",
 response = CustomerResponse.class,
 notes = "Customer must exist")
 @GetMapping("/{id}")
 public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
 return ResponseEntity.ok(customerService.getById(id));
 }

3.4. code屬性

code 屬性表示響應代碼的 HTTP 狀態。 HTTP 狀態碼有多種定義。應該使用其中之一。如果我們不提供，默認值為 200。

4. @ApiResponse

使用 HTTP 狀態代碼返回錯誤是一種常見的做法。我們可以使用@ApiResponse註解來描述操作的具體可能響應。

@ApiOperation註解描述了一個操作和一般返回類型， @ApiResponse註解描述了其餘可能的返回碼。

此外，註釋可以應用於方法級別以及類級別。此外，只有在方法級別尚未定義具有相同代碼的@ApiResponse註釋時，才會解析放在類級別的註釋。換句話說，方法註解優先於類註解。

我們應該在@ApiResponse註釋中使用@ApiResponses註釋，無論我們有一個還是多個響應。如果我們直接使用這個註解，Swagger 是不會解析的。

讓我們在我們的方法上定義@ApiResponses和@ApiResponse註釋：

@ApiResponses(value = {
 @ApiResponse(code = 400, message = "Invalid ID supplied"),
 @ApiResponse(code = 404, message = "Customer not found")})
 @GetMapping("/{id}")
 public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
 return ResponseEntity.ok(customerService.getById(id));
 }

我們也可以使用註解來指定成功響應：

@ApiOperation(value = "Gets customer by ID", notes = "Customer must exist")
 @ApiResponses(value = {
 @ApiResponse(code = 200, message = "OK", response = CustomerResponse.class),
 @ApiResponse(code = 400, message = "Invalid ID supplied"),
 @ApiResponse(code = 404, message = "Customer not found"),
 @ApiResponse(code = 500, message = "Internal server error", response = ErrorResponse.class)})
 @GetMapping("/{id}")
 public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
 return ResponseEntity.ok(customerService.getById(id));
 }

如果我們使用@ApiResponse註解指定成功響應，則無需在@ApiOperation註解中定義它。

現在，讓我們來@ApiResponse中使用的一些屬性。

4.1。 code和message屬性

code和message屬性都是@ApiResponse註解中的必需參數。

與@ApiOperation註解中的 code 屬性一樣，它應該包含響應的 HTTP 狀態代碼。值得一提的是，我們不能使用相同的 code 屬性定義多個@ApiResponse 。

message 屬性通常包含與響應一起出現的人類可讀消息：

@ApiResponse(code = 400, message = "Invalid ID supplied")

4.2. response屬性

有時，端點使用不同的響應類型。例如，我們可以將一種類型用於成功響應，另一種用於錯誤響應。我們可以通過將響應類與響應代碼相關聯來使用可選的response屬性來描述它們。

首先，讓我們定義一個在內部服務器錯誤的情況下將返回的類：

class ErrorResponse {

 private String error;
 private String message;

 // getters and setters
 }

其次，讓我們為內部服務器錯誤添加一個新的@ApiResponse ：

@ApiResponses(value = {
 @ApiResponse(code = 400, message = "Invalid ID supplied"),
 @ApiResponse(code = 404, message = "Customer not found"),
 @ApiResponse(code = 500, message = "Internal server error", response = ErrorResponse.class)})
 @GetMapping("/{id}")
 public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) {
 return ResponseEntity.ok(customerService.getById(id));
 }

5. @ApiOperation和@ApiResponse

綜上所述，下表顯示了@ApiOperation和@ApiResponse註解的主要區別：

@ApiOperation	@ApiResponse
用於描述操作	用於描述操作的可能響應
用於成功響應	用於成功和錯誤響應
只能在方法級別定義	可以在方法或類級別上定義
可以直接使用	只能在@ApiResponses註解中使用
默認代碼屬性值為 200	沒有默認代碼屬性值

六，結論

在本文中，我們了解了@ApiOperation和@ApiResponse註解之間的區別。

與往常一樣，示例的源代碼可 在 GitHub 上獲得。