Swagger-ApiResponse 和 ApiResponses 注解

1. 前言

本節(jié)會繼續(xù)結(jié)合用戶登錄接口方法來為大家介紹 Swagger 中的兩個關(guān)聯(lián)注解 - ApiResponse 和 ApiResponses 注解及所提供的常用屬性，使用率較低或基本不適用的注解屬性就不再介紹了。

ApiResponse 和 ApiResponses 注解在實際項目中的使用頻率較前面所介紹的注解而言相對較低，我們只需要掌握他們最的基本用法和常用屬性即可。

重點講解的屬性：

• ApiResponse 注解的 code 、message 、responseHeaders 屬性；

• ApiResponses 注解的 value 屬性。

2. 什么是 ApiResponse 和 ApiResponses 注解 ？

ApiResponse 注解是作用在接口方法上的注解，用來對該接口方法的一個或多個返回值進行描述，一般不會單獨使用，常常和 @ApiResponses 注解配合使用。

ApiResponses 注解也是作用在接口方法上的注解，作用和 @ApiResponse 注解相同，只是在當有多個 @ApiResponse 注解同時存在時才會使用該注解。

ApiResponse 和 ApiResponses 注解是一組關(guān)系緊密的注解，主要使用的屬性都在 @ApiResponse 注解中。

下面我們來看一下 ApiResponse 和 ApiResponses 兩個注解中都包括哪些常用屬性。

3. 注解主要屬性匯總

ApiResponse 注解

ApiResponses 注解

4. 屬性詳解

4.1 ApiResponse 注解相關(guān)屬性

code () 和 message () 屬性

定義：

code 屬性就是描述接口返回的響應(yīng)數(shù)據(jù)的狀態(tài)碼。

message 屬性就是對接口返回的響應(yīng)數(shù)據(jù)的狀態(tài)碼進行描述。

使用方法：

在 ApiResponse 注解中直接聲明 code 屬性和 message 屬性的值即可，例如，對于用戶登錄接口，我想添加一個值為 666 的狀態(tài)碼，其描述為 success ，代表當接口返回的狀態(tài)碼為 666 時表示請求是成功（success）的。

鑒于上述業(yè)務(wù)場景，我們可以這樣寫：code = 666, message = “success”(現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點看實體類上使用的注解及屬性即可，下同 。

@ApiResponse(code = 666, message = "success")
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

第 1 行，我們在用戶登錄接口方法的上方定義了 ApiResponse 注解的 code 屬性的值為 666，message 屬性的值為 success 來對用戶登錄接口添加特定的返回信息。

顯示結(jié)果：

可以看到，在用紅框框起來的地方就是我們使用 code 屬性和 message 屬性所展示的效果了。

Tips ：

1. 一般而言，在實際項目開發(fā)中，http 協(xié)議自帶的返回狀態(tài)碼已經(jīng)夠用了，不需要開發(fā)者再特殊指定，如果業(yè)務(wù)要求必須遵照一定的規(guī)則，那就只能額外規(guī)定了。

responseHeaders () 屬性

定義：

該屬性就是對接口的返回頭做一個描述，即猶如請求接口時所規(guī)定的請求頭為 ‘a(chǎn)pplication/json’ 類型那樣。

使用方法：

在 ApiResponse 注解中，直接聲明 responseHeaders 屬性的值即可，例如，我想把用戶登錄接口的返回頭類型定義為‘multipart/file’ (這樣定義顯然是不合理的，這里只做演示) ，則可以這樣寫：description = “用戶實體中包含用戶相關(guān)的所有業(yè)務(wù)字段，如有需要請另行添加” 。

@ApiResponse(code = 666, message = "success", responseHeaders = { @ResponseHeader(name = "userLoginHeader", description = "multipart/file") }),
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

第 1 行，我們在用戶實體類的上方定義了 responseHeaders 屬性的值來對用戶登錄接口的返回頭類型添加額外的描述信息。由于篇幅原因這里就不給大家截圖了。

Tips ：

1. responseHeaders 屬性值的定義應(yīng)該按照 http 協(xié)議規(guī)定好的類別進行描述，如果我們所描述的不是 http 協(xié)議所規(guī)定的類型，那么在 Swagger 界面上是不會顯示出來的，這點需要注意。
2. responseHeaders 屬性雖然是 ApiResponse 注解中的，但是使用該屬性需要以數(shù)組的形式使用，即如上述代碼示例，因為該注解源碼中就是這樣定義的。

4.2 ApiResponses 注解相關(guān)屬性

value () 屬性

定義：

ApiResponses 注解的 value 屬性就是對接口的返回狀態(tài)碼及其返回狀態(tài)碼描述進行多條描述，來說明該接口的返回格式有多條額外的描述。

使用方法：

ApiResponses 注解規(guī)定其 value 屬性的類型為 ApiResponse 數(shù)組類型，這就說明 value 屬性只能使用 @ApiResponse 注解的形式進行描述，同時允許描述多條。

例如，在用戶登錄接口中，我想對該接口的返回格式添加兩條額外描述信息，使用方法如下所示。

@ApiResponses( value = { 
@ApiResponse(code = 666, message = "success"),
@ApiResponse(code = 600, message = "error",)})
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

1-3 行，我們在用戶登錄接口方法的上方定義了 ApiResponses 注解的 value 屬性來對該接口的返回格式添加兩條額外描述信息。

顯示結(jié)果：

可以看到，600 和 666 及其 error 和 success 就是我們使用 value 屬性來對該接口的返回格式添加的額外描述信息了。

Tips ：

1. 在實際開發(fā)工作中，value 屬性經(jīng)常被用來描述一個接口方法的多條返回格式，其內(nèi)容應(yīng)該根據(jù)業(yè)務(wù)文檔所規(guī)定的要求進行描述。
2. value 屬性內(nèi)容的填充形式就如上述代碼所示，其中 value 這個單詞可以不顯式的寫出來，Swagger 會默認隱藏。
3. ApiResponses 注解不能單獨使用，因為他只有一個類型為 ApiResponse 數(shù)組形式的 value 屬性，即要使用 ApiResponses 注解就必須要填充 value 屬性。

5. 小結(jié)

本小節(jié)對 Swagger 中的 ApiResponse 和 ApiResponses 注解，及其該注解中的常用屬性，做了詳細介紹，針對兩個注解中，經(jīng)常在實際項目開發(fā)中使用的屬性，采用圖文并茂的方式進行了重點介紹和應(yīng)用剖析。

Tips : 值得注意的是 @ApiResponse 注解一般不可以單獨拿來使用，需要搭配 @ApiResponses 注解一起來使用，這樣才能在 Swagger-ui 界面看到使用效果。

在學習 ApiResponse 和 ApiResponses 注解及其常用屬性時，各位同學應(yīng)該在清楚常見的 http 狀態(tài)碼及其描述都有哪些以及什么是接口的請求頭、響應(yīng)頭的基礎(chǔ)上進行學習，因為這兩個注解都是針對接口的返回數(shù)據(jù)及其格式而言的，其他地方無法使用。