Swagger-ApiParam 注解詳解

1. 前言

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

ApiParam 注解一般會(huì)結(jié)合 ApiOperation 注解以及 Api 注解一起來(lái)使用。

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

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

2. 什么是 ApiParam 注解？

ApiParam 注解，是可以作用在接口方法上面，以及接口方法中的參數(shù)位置的注解，其主要是用來(lái)給接口中的參數(shù)定義相關(guān)參數(shù)說(shuō)明，主要是為了，幫助相關(guān)人員理解接口中每個(gè)參數(shù)的含義。

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

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

3. ApiParam 注解主要屬性匯總

4. 屬性詳解

4.1 name() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們?cè)?login 接口方法的上方使用了 @ApiParam 注解的 name 屬性來(lái)描述該接口中的參數(shù)名稱。

顯示結(jié)果：

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

Tips ：

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

4.2 value() 屬性

定義：

該屬性就是對(duì)接口中的參數(shù)做一個(gè)簡(jiǎn)要的描述，即來(lái)說(shuō)明接口中的參數(shù)是用來(lái)做什么的。

使用方法：

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

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

代碼解釋：

第1行，我們?cè)?login 方法的上方使用了 @ApiParam 注解的 name 屬性和 value 屬性來(lái)對(duì)接口方法中的 user 參數(shù)做一個(gè)簡(jiǎn)單必要的說(shuō)明。

顯示結(jié)果：

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

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

在本節(jié)的開(kāi)篇中，就已經(jīng)說(shuō)明了 @ApiParame 既可以寫(xiě)在接口方法的上方，也可以寫(xiě)在接口中參數(shù)的位置，在上圖中我們是把注解寫(xiě)在了接口方法的上方，那么現(xiàn)在我們來(lái)看一下，將注解寫(xiě)在接口中參數(shù)的位置時(shí)又是一種什么效果吧：

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

代碼解釋：

第1行，我們修改了 @ApiParam 注解的位置，把注解寫(xiě)到了和接口參數(shù)相同的位置，通過(guò)這種方式來(lái)對(duì) user 參數(shù)做一個(gè)簡(jiǎn)單必要的說(shuō)明。

顯示結(jié)果：

我們可以看到，在 Parameters 內(nèi)容區(qū)域的 Description 位置，已經(jīng)顯示出了我們使用 value 來(lái)對(duì) user 參數(shù)所描述的信息，上述兩種使用 value 的情況請(qǐng)同學(xué)們特別注意。

Tips ：

1. value 屬性用于描述接口中字段的說(shuō)明，一般是一些必要的重要信息，不要描述很長(zhǎng)的一段話，如果是一般簡(jiǎn)單性的描述，那還是不要寫(xiě)出來(lái)為好。
2. 出于國(guó)人習(xí)慣的考慮，在描述 value 屬性的值時(shí)，盡量使用中文來(lái)描述，這樣可以做到顯而易見(jiàn)、通俗易懂。
3. 鑒于 value 屬性的特殊情況，同學(xué)們?cè)谑褂脮r(shí)應(yīng)該注意：如果接口的方法參數(shù)就一個(gè)且該參數(shù)很好理解，這種情況就在接口方法的上面描述；如果接口的方法參數(shù)不便于理解，這種情況就要在接口的方法位置來(lái)描述，請(qǐng)同學(xué)們根據(jù)情況合理使用。

4.3 defaultValue() 屬性

定義：

該屬性就是對(duì)接口方法中的參數(shù)默認(rèn)值進(jìn)行描述，即對(duì)接口中存在默認(rèn)值的參數(shù)進(jìn)行簡(jiǎn)單的描述。

使用方法：

在 ApiParam 注解中，聲明 defaultValue 的值即可，如果沒(méi)有描述則默認(rèn)值為空。例如，如果我想對(duì)用戶接口方法中的 user 對(duì)象參數(shù)中的一個(gè)屬性，添加默認(rèn)值描述，那么我可以這樣寫(xiě) defaultValue = “ admin ”(嚴(yán)格來(lái)講，user 參數(shù)的默認(rèn)值應(yīng)該是一個(gè) json 串，這里為了演示就簡(jiǎn)單描述了)，如下代碼段所示。

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

代碼解釋：

第1行，我們?cè)?login 接口方法的上方使用了 @ApiParam 注解的 defaultValue 屬性來(lái)對(duì)用戶登錄接口中存在默認(rèn)值的屬性進(jìn)行描述。

defaultValue 屬性并沒(méi)有直接的界面顯示效果，這個(gè)作用效果可以在使用 swagger-ui 進(jìn)行接口調(diào)試的時(shí)候可以很直觀的看到。

當(dāng)我們?cè)趥鬟f某一參數(shù)時(shí)，如果我們沒(méi)有給該參數(shù)填充數(shù)據(jù)，同時(shí)該參數(shù)被 defaultValue 屬性所描述，此時(shí)該參數(shù)的數(shù)據(jù)就會(huì)變?yōu)?defaultValue 屬性所描述的值了。這一點(diǎn)在如何使用 swagger-ui 進(jìn)行接口調(diào)試小節(jié)中會(huì)詳細(xì)介紹。

Tips ：

1. defaultValue 屬性不要濫用，其用于對(duì)接口方法中存在默認(rèn)值的參數(shù)進(jìn)行說(shuō)明，如果在接口方法中不存在有默認(rèn)值的參數(shù)，那就不要使用該屬性。
2. 如果一個(gè)接口方法中存在多個(gè)有默認(rèn)值的參數(shù)需要說(shuō)明，那么請(qǐng)使用 @ApiParam 注解的 defaultValue 屬性來(lái)對(duì)參數(shù)分別進(jìn)行說(shuō)明。

4.4 required() 屬性

定義：

該屬性就是對(duì)接口方法中參數(shù)傳遞的必要性做一個(gè)約定，即接口方法中的參數(shù)哪些是必須傳遞的，哪些是非必須傳遞的。

使用方法：

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

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

代碼解釋：

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

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

顯示結(jié)果：

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

4.5 allowableValues() 屬性

定義：

該屬性就是對(duì)接口方法中的參數(shù)的可取值范圍進(jìn)行描述。

使用方法：

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

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

代碼解釋：

第1行，我們?cè)?getUserInfo 接口方法的上方使用了 @ApiParam 注解的 allowableValues 屬性來(lái)對(duì)用戶 id 值的可取范圍做一個(gè)限制。

當(dāng)我們以上述接口方法的形式來(lái)使用 allowableValues 屬性時(shí)并不能在 swagger-ui 界面看到任何效果，這應(yīng)該是 swagger-ui 的一個(gè) bug ，至于使用效果如何，請(qǐng)看后面使用 swagger-ui 進(jìn)行接口調(diào)試小節(jié)的內(nèi)容。

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

階段小結(jié)（一）

以上是對(duì) ApiParam 注解中經(jīng)常使用的五個(gè)屬性進(jìn)行的詳細(xì)介紹，name , values , defatluValue , required , allowableValues 掌握這五個(gè)屬性的使用搭配習(xí)慣是真正用好 ApiParam 注解的重要前提。在學(xué)習(xí)這五個(gè)屬性時(shí)，大家應(yīng)該結(jié)合 ApiOperation 注解來(lái)對(duì)比并總結(jié)它們之間的差異，通過(guò)不斷的使用來(lái)發(fā)現(xiàn)它們的使用規(guī)律，這一點(diǎn)很重要。

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

4.6 example() 和 hidden() 屬性

定義：

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

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

使用方法：

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

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

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

代碼解釋：

第1行，我們?cè)?getUserInfo 接口方法中對(duì) userId 參數(shù)通過(guò) example 屬性描述了示例值，對(duì) username 進(jìn)行了隱藏。

Tips ：

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

階段小結(jié)（二）

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

5. 小結(jié)

本小節(jié)對(duì) Swagger 中另一個(gè)最經(jīng)常使用的 ApiParam 注解及其該注解的各個(gè)屬性做了詳細(xì)的講解，針對(duì) ApiParam 注解中經(jīng)常在實(shí)際項(xiàng)目開(kāi)發(fā)中使用的屬性采用圖文并茂的方式進(jìn)行了重點(diǎn)介紹和應(yīng)用剖析，對(duì)于一些在實(shí)際項(xiàng)目開(kāi)發(fā)中使用基本很少的注解做了概要講解。

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