Swagger-ApiParam 注解詳解

1. 前言

本節(jié)會繼續(xù)結合一個用戶登錄接口給大家介紹 Swagger 中的另一個核心注解 - ApiParam 注解及所提供的常用屬性。

ApiParam 注解一般會結合 ApiOperation 注解以及 Api 注解一起來使用。

重點講解的屬性：name 、value 、defaultValue 、allowableValues 、required ；
概要講解的屬性：access、allowMultiple、example、hidden。

希望大家在學習本節(jié)過程中能夠分清主次，有的放矢。

2. 什么是 ApiParam 注解？

ApiParam 注解，是可以作用在接口方法上面，以及接口方法中的參數位置的注解，其主要是用來給接口中的參數定義相關參數說明，主要是為了，幫助相關人員理解接口中每個參數的含義。

ApiParam 注解同樣也提供了豐富的屬性，來允許我們對接口中的參數添加描述信息，包括該參數的具體含義、參數是否必須傳遞等。

下面我們來看一下 ApiParam 注解中都包括哪些主要屬性。

3. ApiParam 注解主要屬性匯總

4. 屬性詳解

4.1 name() 屬性

定義：

該屬性就是描述接口中參數的名稱。

使用方法：

在 ApiParam 注解中聲明 name 的值即可。例如，對于用戶接口而言，在本例中，需要傳遞的參數是一個 user 對象，所以我們需要將 name 的值寫為 ‘user’就可以了，這樣，我們就能很清楚的知道，這個接口方法中傳遞的參數是一個 user 對象了，如下代碼段所示（現在你不需要理解業(yè)務代碼代表什么意思，重點看接口方法上使用的注解及屬性即可，下同）。

@ApiParam(name = "user")
public User login(User user){
    // 用戶登錄業(yè)務邏輯
}

代碼解釋：

第1行，我們在 login 接口方法的上方使用了 @ApiParam 注解的 name 屬性來描述該接口中的參數名稱。

顯示結果：

可以看到，在 Parameters 內容區(qū)中用紅框圈起來的 Parameter 參數的名稱就是我們使用 name 屬性來描述的接口參數名稱。

Tips ：

1. 在實際開發(fā)工作中，name 屬性的值一般都是根據接口方法中的形參來描述，即接口方法中默認聲明的參數名稱，除非有特殊說明才可以描述與形參名稱不同的值。
2. 如果我們沒有使用 name 屬性來描述參數的名稱，則參數名稱默認為接口中自帶的參數名稱。

4.2 value() 屬性

定義：

該屬性就是對接口中的參數做一個簡要的描述，即來說明接口中的參數是用來做什么的。

使用方法：

在 ApiParam 注解中聲明 value 的值即可，如果沒有描述則默認值為空。例如，就用戶接口而言，該接口中的參數是一個用戶對象，則我們可以在 value 屬性中添加這樣的描述：‘用戶對象，用于用戶登錄檢測，必傳’，如下代碼段所示。

@ApiParam(name="user", value = "用戶對象，用于用戶登錄檢測，必傳")
public User login(User user){
    // 用戶登錄業(yè)務邏輯
}

代碼解釋：

第1行，我們在 login 方法的上方使用了 @ApiParam 注解的 name 屬性和 value 屬性來對接口方法中的 user 參數做一個簡單必要的說明。

顯示結果：

我們可以看到在 Parameters 內容區(qū)域的 Description 紅框圈起來的地方并沒有顯示出我們使用 value 屬性所描述的信息，從某種意義上（Swagger 源碼角度）講，這是 Swagger-UI 的一個 Bug ，但是從使用角度來講可能就是我們用錯了 @ApiParam 注解。

如果我們想在 Description 中顯示我們所描述的信息，我們又該怎么做呢？

在本節(jié)的開篇中，就已經說明了 @ApiParame 既可以寫在接口方法的上方，也可以寫在接口中參數的位置，在上圖中我們是把注解寫在了接口方法的上方，那么現在我們來看一下，將注解寫在接口中參數的位置時又是一種什么效果吧：

public User login(@ApiParam(name="user", value = "用戶對象，用于用戶登錄檢測，必傳") User user){
    // 用戶登錄業(yè)務邏輯
}

代碼解釋：

第1行，我們修改了 @ApiParam 注解的位置，把注解寫到了和接口參數相同的位置，通過這種方式來對 user 參數做一個簡單必要的說明。

顯示結果：

我們可以看到，在 Parameters 內容區(qū)域的 Description 位置，已經顯示出了我們使用 value 來對 user 參數所描述的信息，上述兩種使用 value 的情況請同學們特別注意。

Tips ：

1. value 屬性用于描述接口中字段的說明，一般是一些必要的重要信息，不要描述很長的一段話，如果是一般簡單性的描述，那還是不要寫出來為好。
2. 出于國人習慣的考慮，在描述 value 屬性的值時，盡量使用中文來描述，這樣可以做到顯而易見、通俗易懂。
3. 鑒于 value 屬性的特殊情況，同學們在使用時應該注意：如果接口的方法參數就一個且該參數很好理解，這種情況就在接口方法的上面描述；如果接口的方法參數不便于理解，這種情況就要在接口的方法位置來描述，請同學們根據情況合理使用。

4.3 defaultValue() 屬性

定義：

該屬性就是對接口方法中的參數默認值進行描述，即對接口中存在默認值的參數進行簡單的描述。

使用方法：

在 ApiParam 注解中，聲明 defaultValue 的值即可，如果沒有描述則默認值為空。例如，如果我想對用戶接口方法中的 user 對象參數中的一個屬性，添加默認值描述，那么我可以這樣寫 defaultValue = “ admin ”(嚴格來講，user 參數的默認值應該是一個 json 串，這里為了演示就簡單描述了)，如下代碼段所示。

public User login(@ApiParam(defaultValue = " admin") User user){
    // 用戶登錄業(yè)務邏輯
}

代碼解釋：

第1行，我們在 login 接口方法的上方使用了 @ApiParam 注解的 defaultValue 屬性來對用戶登錄接口中存在默認值的屬性進行描述。

defaultValue 屬性并沒有直接的界面顯示效果，這個作用效果可以在使用 swagger-ui 進行接口調試的時候可以很直觀的看到。

當我們在傳遞某一參數時，如果我們沒有給該參數填充數據，同時該參數被 defaultValue 屬性所描述，此時該參數的數據就會變?yōu)?defaultValue 屬性所描述的值了。這一點在如何使用 swagger-ui 進行接口調試小節(jié)中會詳細介紹。

Tips ：

1. defaultValue 屬性不要濫用，其用于對接口方法中存在默認值的參數進行說明，如果在接口方法中不存在有默認值的參數，那就不要使用該屬性。
2. 如果一個接口方法中存在多個有默認值的參數需要說明，那么請使用 @ApiParam 注解的 defaultValue 屬性來對參數分別進行說明。

4.4 required() 屬性

定義：

該屬性就是對接口方法中參數傳遞的必要性做一個約定，即接口方法中的參數哪些是必須傳遞的，哪些是非必須傳遞的。

使用方法：

在 ApiParam 注解中，聲明 required 的值即可，如果沒有描述則默認值為 false ， 即參數為非必須傳遞。例如，如果我想把用戶登錄接口方法中的參數描述為必須傳遞，那么我可以這樣寫 required = true，如下代碼段所示。

public User login(@ApiParam(required = true) User user){
    // 用戶登錄業(yè)務邏輯
}

代碼解釋：

第1行，我們在 login 接口方法的上方使用了 @ApiParam 注解的 required 屬性來將用戶登錄接口中的屬性描述為必須傳遞。

如果想要看到 required 屬性的作用效果，就需要我們改變?yōu)g覽器地址欄的路徑了：在瀏覽器地址欄中輸入：swagger-ui 訪問路徑 + /v2/api-docs（至于為什么是這個路徑，在后面的文章中會詳細說明），在輸入完上述 url 之后我們會看到一個由多個 json 串所組成的界面，而這些 json 串的內容正是我們所寫的接口。

顯示結果：

可以看到，我在用戶登錄接口的 json 串中用紅框圈起來的就是我們使用 required 所描述的結果了。

4.5 allowableValues() 屬性

定義：

該屬性就是對接口方法中的參數的可取值范圍進行描述。

使用方法：

在 ApiParam 注解中，聲明 allowableValues 的值即可，如果沒有描述則默認值為空，值得注意的是，使用該屬性需要遵循特性的描述格式。例如，如果我想把用戶登錄接口方法中的參數描述為必須傳遞，那么我可以這樣寫 required = true，如下代碼段所示。

public User getUserInfo(@ApiParam(allowableValues = "range[1,10]") int userId){
    // 獲取用戶信息業(yè)務邏輯
}

代碼解釋：

第1行，我們在 getUserInfo 接口方法的上方使用了 @ApiParam 注解的 allowableValues 屬性來對用戶 id 值的可取范圍做一個限制。

當我們以上述接口方法的形式來使用 allowableValues 屬性時并不能在 swagger-ui 界面看到任何效果，這應該是 swagger-ui 的一個 bug ，至于使用效果如何，請看后面使用 swagger-ui 進行接口調試小節(jié)的內容。

Tips ： 在實際項目開發(fā)工作中，allowableValues 使用的頻率并不是很高，一般都是為了避免參數傳遞不合法才設置該屬性。

階段小結（一）

以上是對 ApiParam 注解中經常使用的五個屬性進行的詳細介紹，name , values , defatluValue , required , allowableValues 掌握這五個屬性的使用搭配習慣是真正用好 ApiParam 注解的重要前提。在學習這五個屬性時，大家應該結合 ApiOperation 注解來對比并總結它們之間的差異，通過不斷的使用來發(fā)現它們的使用規(guī)律，這一點很重要。

在詳細講解完 ApiParam 重要屬性之后，下面我將針對，在 ApiParam 注解中使用頻率不是很高，但是有時也會用到的一些屬性做概要性講解，這些屬性分別是：access、allowMultiple、example、hidden 。

4.6 example() 和 hidden() 屬性

定義：

example() 屬性就是描述接口方法中的一個參數的示例值。

hidden() 屬性就是控制接口方法中的參數在 Swagger 界面中的顯隱性。

使用方法：

example() 屬性默認值為空，當我們需要對接口中的方法添加示例值描述時，可以使用該屬性進行描述。例如，對于獲取用戶信息方法而言，需要傳遞的參數為用戶的 id ，則我可以描述一個示例值為 1。

hidden() 屬性允許我們在 Swagger 生成的接口列表界面上，控制接口方法中的參數是否需要顯示，默認值為 false，即接口方法中的參數顯示，為true時則接口方法中的參數不顯示，如下代碼段所示。

public User getUserInfo(@ApiParam(example = "1") int userId, @ApiParam(hidden = true) String username){
    // 獲取用戶信息業(yè)務邏輯
}

代碼解釋：

第1行，我們在 getUserInfo 接口方法中對 userId 參數通過 example 屬性描述了示例值，對 username 進行了隱藏。

Tips ：

1. 接口方法中參數的顯隱控制應該根據特定安全策略和特定客戶需求來決定顯隱，不能無故隱藏接口參數，更不能頻繁的切換接口參數的顯隱。
2. 在實際工作中，應該根據業(yè)務要求來合理描述接口中參數的示例值，不能隨便描述，更不能描述不清楚。

階段小結（二）

以上則是 ApiParam 注解中的輔助使用屬性的概要介紹，對于剩下的 access、allowMultiple 屬性在實際項目開發(fā)中幾乎很少使用，在這里就不再介紹了，如果大家感興趣可以去 Swagger 的官網查詢相關資料來了解。

5. 小結

本小節(jié)對 Swagger 中另一個最經常使用的 ApiParam 注解及其該注解的各個屬性做了詳細的講解，針對 ApiParam 注解中經常在實際項目開發(fā)中使用的屬性采用圖文并茂的方式進行了重點介紹和應用剖析，對于一些在實際項目開發(fā)中使用基本很少的注解做了概要講解。

在學習 @ApiParam 注解及其屬性時，各位同學應該對比 @ApiOperation 注解及其屬性之間的使用差異，通過差異比較總結出適合自己的使用規(guī)律和使用方法才是最重要的。