原文

https://www.baeldung.com/swagger-apioperation-vs-apiresponse

引言

本文內(nèi)容討論的是?@ApiOperation?和?@ApiResponse?注解的優(yōu)劣。

介紹Swagger

一個RestFul最重要的是具備“自描述能力”，所謂的自描述能力是能在返回結(jié)果的同時，告知客戶端調(diào)用下 一步的行為，Swagger在一定程度上封裝和規(guī)范了這些操作。

什么是Swagger？

Swagger represents a set of open-source tools built around OpenAPI Specification. It can help us design, build, document, and consume REST APIs.

Swagger代表了一套圍繞OpenAPI規(guī)范建立的開源工具。它可以幫助我們設(shè)計(jì)、構(gòu)建、記錄REST APIs接口。其中最為常用的注解便是 @ApiOperation 和 @ApiResponse。

@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));
???}
}


下面分別介紹這兩個注解的使用，最后是進(jìn)行對比。

@ApiOperation

關(guān)鍵點(diǎn)：描述單獨(dú)的一個操作和行為。通常用于單一的路徑或者h(yuǎn)ttp請求方法。

@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的一些屬性：

value

value屬性主要是描述接口的行為，注意參數(shù)大小不能超過120個字符。從長度限制來看要盡可能的簡化注解的描述。

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


notes

個人認(rèn)為把這個注解當(dāng)成comment更為合適，notes和value的區(qū)別是可以填寫的長度限制為text，意思是更為詳細(xì)的敘述接口功能。

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


response

@ApiOperation注解中定義的響應(yīng)屬性應(yīng)該包含一般的響應(yīng)類型。大部分情況下我們會把返回結(jié)果用統(tǒng)一的對象包裝：

class?CustomerResponse?{
??
???private?Long?id;
???private?String?firstName;
???private?String?lastName;
??
???//?getters?and?setters
}


更為常見的是使用類似AjaxDto這樣的對象封裝響應(yīng)Code，響應(yīng)Msg和響應(yīng)數(shù)據(jù)Data。

在使用的過程中設(shè)置Class類，在Swagger文檔中將會對應(yīng)生成相關(guān)的對象以及

@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));
}


code

也就是響應(yīng)code碼，對應(yīng) Http Status

@ApiResponse

@ApiResponse 注解主要用于描述接口的返回狀態(tài)碼以及對應(yīng)的返回信息。雖然@ApiOperation注解描述了操作和一般的返回類型，但@ApiResponse注解描述了其余可能的狀態(tài)碼。

@ApiResponse注解的特點(diǎn)是方法注解優(yōu)先于類注解。我們應(yīng)該在@ApiResponses注解中使用@ApiResponse注解，無論我們有一個還是多個響應(yīng)。

下面是正確的@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));??
}


對于特殊的狀態(tài)碼進(jìn)行描述：

@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));??
}


code 和 message

與@ApiOperation注解中的code屬性一樣，它應(yīng)該包含響應(yīng)的HTTP狀態(tài)代碼。值得一提的是，我們不能用相同的代碼屬性定義一個以上的@ApiResponse。

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


response

response可以為特殊的狀態(tài)碼指定對象：

class?ErrorResponse?{

????private?String?error;
????private?String?message;

????//?getters?and?setters
}


其次，讓我們?yōu)閮?nèi)部服務(wù)器錯誤添加一個新的@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));
}


@ApiOperation 和 @ApiResponse 區(qū)別

@ApiOperation@ApiResponse通用用于描述一個操作用于描述操作的可能的響應(yīng)通常用于成功的請求可以用于成功或者失敗的各種請求只能用在方法級別可以用于類或者方法級別可以直接使用只能在@ApiResponses注解中使用。默認(rèn)code為200沒有默認(rèn)值