Swagger-ApiResponse 和 ApiResponses 注解

1. 前言

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

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

重點講解的屬性：

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

• ApiResponses 注解的 value 屬性。

2. 什么是 ApiResponse 和 ApiResponses 注解 ？

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

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

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

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

3. 注解主要屬性匯總

ApiResponse 注解

ApiResponses 注解

4. 屬性詳解

4.1 ApiResponse 注解相關屬性

code () 和 message () 屬性

定義：

code 屬性就是描述接口返回的響應數據的狀態碼。

message 屬性就是對接口返回的響應數據的狀態碼進行描述。

使用方法：

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

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

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

代碼解釋：

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

顯示結果：

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

Tips ：

1. 一般而言，在實際項目開發中，http 協議自帶的返回狀態碼已經夠用了，不需要開發者再特殊指定，如果業務要求必須遵照一定的規則，那就只能額外規定了。

responseHeaders () 屬性

定義：

該屬性就是對接口的返回頭做一個描述，即猶如請求接口時所規定的請求頭為 ‘application/json’ 類型那樣。

使用方法：

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

@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 屬性值的定義應該按照 http 協議規定好的類別進行描述，如果我們所描述的不是 http 協議所規定的類型，那么在 Swagger 界面上是不會顯示出來的，這點需要注意。
2. responseHeaders 屬性雖然是 ApiResponse 注解中的，但是使用該屬性需要以數組的形式使用，即如上述代碼示例，因為該注解源碼中就是這樣定義的。

4.2 ApiResponses 注解相關屬性

value () 屬性

定義：

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

使用方法：

ApiResponses 注解規定其 value 屬性的類型為 ApiResponse 數組類型，這就說明 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 屬性來對該接口的返回格式添加兩條額外描述信息。

顯示結果：

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

Tips ：

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

5. 小結

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

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

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