Swagger-ApiImplicitParam 注解詳解

1. 前言

本節會繼續結合一個用戶登錄接口給大家介紹 Swagger 中的另一個注解 - ApiImplicitParam注解及所提供的常用屬性。

ApiImplicitParam 注解經常來配合其他注解一同使用，并不會經常單獨拿來使用，所以，對于 ApiImplicitParam 注解，我們只需要了解它的作用和注意事項即可，不必重點掌握。

重點講解的屬性：name 、value 、defaultValue 、 required ；
概要講解的屬性：paramType 、 dataType 。

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

2. 什么是 ApiImplicitParam 注解？

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

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

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

3. ApiImplicitParam 注解主要屬性匯總

4. 屬性詳解

4.1 name() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們在用戶登錄接口方法的上方，定義了 ApiImplicitParam 注解的 name 屬性的值，來描述該方法中參數的名稱。

顯示結果：

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

Tips ：

1. 在實際開發工作中，name 屬性的值通常被描述為接口方法中參數的名稱，一般情況不用單獨來描述。
2. name 屬性的使用不是必須的，即每個接口方法中不一定要使用 name 屬性，name 屬性的適用范圍應該根據接口業務要求來定。

4.2 value() 和 defaultValue() 屬性

定義：

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

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

使用方法：

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

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

代碼解釋：

第1行，我們在用戶登錄接口方法的上方，定義了 ApiImplicitParam 注解的 value 屬性的值來對該方法中的參數進行解釋說明。

顯示結果：

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

對于 defaultValue() 屬性，該屬性值的定義需要根據接口中參數的類型而定，比如該用戶登錄接口中的參數類型是一個 user 對象，所以我們在描述的時候應該把 defaultValue() 屬性的值使用 json 來填充。

defaultValue() 屬性的演示我們會在后續章節-注解組合實戰中給大家統一演示，希望大家關注。

Tips ： 在實際項目開發工作中，value 屬性一般是每個接口方法都需要使用，而 value 屬性值的定義則是需要做到簡單扼要，切合實際，不能隨意描述，需要根據具體業務場景來描述。

4.3 required() 屬性

定義：

該屬性就是對接口方法中參數傳遞的必要性進行約束，就是該接口方法中的參數是不是一定要傳遞。

使用方法：

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

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

代碼解釋：

第1行，我們在用戶登錄接口方法的上方定義了 ApiImplicitParam 注解的 required 屬性的值來要求該參數必須傳遞。

顯示結果：

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

Tips ：

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

階段小結（一）

以上是對 ApiImpliciParam 注解中，經常使用的四個屬性進行的詳細介紹，name 、value 、defaultValue 、 required 這四個屬性在使用 ApiImpliciParam 注解時經常使用，希望各位可以正確理解各屬性所表達的含義，這是用好 ApiImpliciParam 注解的關鍵。

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

4.4 paramType() 和 dataType() 屬性

定義：

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

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

使用方法：

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

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

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

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

代碼解釋：

第1行，我們在用戶登錄接口方法的上方定義了 ApiImplicitParam 注解的 paramType 屬性和 dataType 屬性來對接口方法中參數的使用位置和類型進行了描述。

由于篇幅限制，該部分注解的演示請參考注解組合實戰章節。

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

階段小結（二）

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

5. 小結

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

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