Swagger-ApiImplicitParam 注解詳解

1. 前言

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

ApiImplicitParam 注解經(jīng)常來配合其他注解一同使用，并不會(huì)經(jīng)常單獨(dú)拿來使用，所以，對(duì)于 ApiImplicitParam 注解，我們只需要了解它的作用和注意事項(xiàng)即可，不必重點(diǎn)掌握。

重點(diǎn)講解的屬性：name 、value 、defaultValue 、 required ；
概要講解的屬性：paramType 、 dataType 。

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

2. 什么是 ApiImplicitParam 注解？

ApiImplicitParam 注解是作用在接口方法上的注解，用來對(duì)該接口中的參數(shù)進(jìn)行簡短的描述，常常和 ApiParam 注解一起搭配使用。

ApiImplicitParam 注解提供了豐富的屬性，來允許我們自定義接口方法中參數(shù)的描述信息，包括接口中參數(shù)是否必傳、參數(shù)類型等。

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

3. ApiImplicitParam 注解主要屬性匯總

4. 屬性詳解

4.1 name() 屬性

定義：

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

使用方法：

在 ApiImplicitParam 注解中聲明 name 的值即可。例如，對(duì)于用戶接口，該接口中存在一個(gè)用戶對(duì)象參數(shù) user ，我們只需要將 name 的值寫為 ‘user’ 就好了，即表明該接口中有一個(gè)名稱為 user 的參數(shù)（現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點(diǎn)看接口類上使用的注解及屬性即可，下同）。

@ApiImplicitParam(name = "user")
public ServerResponse<User> userLogin(User user){
    // do something...
}

代碼解釋：

第1行，我們?cè)谟脩舻卿浗涌诜椒ǖ纳戏剑x了 ApiImplicitParam 注解的 name 屬性的值，來描述該方法中參數(shù)的名稱。

顯示結(jié)果：

可以看到，在使用紅色框框起來的地方就是我們使用 name 屬性描述的參數(shù)名稱了。

Tips ：

1. 在實(shí)際開發(fā)工作中，name 屬性的值通常被描述為接口方法中參數(shù)的名稱，一般情況不用單獨(dú)來描述。
2. name 屬性的使用不是必須的，即每個(gè)接口方法中不一定要使用 name 屬性，name 屬性的適用范圍應(yīng)該根據(jù)接口業(yè)務(wù)要求來定。

4.2 value() 和 defaultValue() 屬性

定義：

value() 屬性就是對(duì)接口方法中的參數(shù)，進(jìn)行簡單必要的描述，即來描述接口方法中的參數(shù)是用來干什么的。

defaultValue() 屬性就是定義接口方法中參數(shù)的默認(rèn)值。

使用方法：

對(duì)于 value() 屬性，在 ApiImplicitParam 注解中聲明 value 的值即可，如果沒有描述則默認(rèn)值為空。例如，就用戶登錄接口而言，其中的 user 參數(shù)是用來接收用戶的登錄數(shù)據(jù)的，所以我們可以這樣寫，value = ‘user對(duì)象，用來接收用戶的登錄數(shù)據(jù)’ 如下代碼段所示。

@ApiImplicitParam(value = "user對(duì)象，用來接收用戶的登錄數(shù)據(jù)")
public ServerResponse<User> userLogin(User user){
    // do something...
}

代碼解釋：

第1行，我們?cè)谟脩舻卿浗涌诜椒ǖ纳戏?，定義了 ApiImplicitParam 注解的 value 屬性的值來對(duì)該方法中的參數(shù)進(jìn)行解釋說明。

顯示結(jié)果：

我們可以看到在紅色框框起來的地方就是我們對(duì)接口方法中參數(shù)的解釋說明。

對(duì)于 defaultValue() 屬性，該屬性值的定義需要根據(jù)接口中參數(shù)的類型而定，比如該用戶登錄接口中的參數(shù)類型是一個(gè) user 對(duì)象，所以我們?cè)诿枋龅臅r(shí)候應(yīng)該把 defaultValue() 屬性的值使用 json 來填充。

defaultValue() 屬性的演示我們會(huì)在后續(xù)章節(jié)-注解組合實(shí)戰(zhàn)中給大家統(tǒng)一演示，希望大家關(guān)注。

Tips ： 在實(shí)際項(xiàng)目開發(fā)工作中，value 屬性一般是每個(gè)接口方法都需要使用，而 value 屬性值的定義則是需要做到簡單扼要，切合實(shí)際，不能隨意描述，需要根據(jù)具體業(yè)務(wù)場景來描述。

4.3 required() 屬性

定義：

該屬性就是對(duì)接口方法中參數(shù)傳遞的必要性進(jìn)行約束，就是該接口方法中的參數(shù)是不是一定要傳遞。

使用方法：

在 ApiImplicitParam 注解中聲明 required 的值即可，如果沒有描述則默認(rèn)值為 false 。例如，如果我想規(guī)定用戶登錄接口方法中的 user 參數(shù)是必須傳遞的，那么我可以這樣寫：required = true ,如下代碼段所示。

@ApiImplicitParam(name = "user", required = true)
public ServerResponse<User> userLogin(User user){
    // do something...
}

代碼解釋：

第1行，我們?cè)谟脩舻卿浗涌诜椒ǖ纳戏蕉x了 ApiImplicitParam 注解的 required 屬性的值來要求該參數(shù)必須傳遞。

顯示結(jié)果：

在我用紅框圈起來的地方，我們可以看到在 user 的右上角有紅色的 required 標(biāo)識(shí)，這就是我們使用 required 規(guī)定參數(shù)必傳的效果了。

Tips ：

1. required() 屬性需要和 name() 屬性一起來使用才能起到約束參數(shù)是否必傳的目的，如果我們不使用 name() 屬性，則 Swagger 就不會(huì)知道哪個(gè)參數(shù)需要 required 屬性來描述。
2. required() 屬性的定義請(qǐng)根據(jù)業(yè)務(wù)文檔要求來描述，不要隨意描述。

階段小結(jié)（一）

以上是對(duì) ApiImpliciParam 注解中，經(jīng)常使用的四個(gè)屬性進(jìn)行的詳細(xì)介紹，name 、value 、defaultValue 、 required 這四個(gè)屬性在使用 ApiImpliciParam 注解時(shí)經(jīng)常使用，希望各位可以正確理解各屬性所表達(dá)的含義，這是用好 ApiImpliciParam 注解的關(guān)鍵。

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

4.4 paramType() 和 dataType() 屬性

定義：

paramType() 屬性就是用來描述接口中的參數(shù)應(yīng)該用在哪個(gè)地方，常用的位置有：header、query 、path 。

dataType() 屬性就是用來描述接口中參數(shù)的類型。

使用方法：

如果我們需要描述接口方法參數(shù)的使用位置，那么我們可以直接在 ApiImplicitParam 注解中聲明 paramType 的值即可。

dataType() 屬性的默認(rèn)值為 String 字符串類型，如果我們部隊(duì)參數(shù)進(jìn)行描述，則 Swagger 默認(rèn)會(huì)使用該類型，如果需要明確定義接口中參數(shù)的類型，那就在 ApiImplicitParam 注解中聲明 dataType 的值即可。

上述兩種情況如下代碼段所示：

@ApiImplicitParam(name = "user", paramType = "header", dataType = "User")
public ServerResponse<User> userLogin(User user){
    // do something...
}

代碼解釋：

第1行，我們?cè)谟脩舻卿浗涌诜椒ǖ纳戏蕉x了 ApiImplicitParam 注解的 paramType 屬性和 dataType 屬性來對(duì)接口方法中參數(shù)的使用位置和類型進(jìn)行了描述。

由于篇幅限制，該部分注解的演示請(qǐng)參考注解組合實(shí)戰(zhàn)章節(jié)。

Tips ： 在實(shí)際工作中，paramType 一般不常用，而 dataType 往往每個(gè)接口方法都需要使用。

階段小結(jié)（二）

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

5. 小結(jié)

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

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