Swagger-Api 注解詳解

1. 前言

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

Api 注解和 ApiOperation 注解一樣，在 Swagger 中都扮演著非常重要的角色，Api 注解一般都會配合 ApiOperation 注解一起來使用。

重點講解的屬性：value 、tags 、description ;
概要講解的屬性：consumes、produces、protocols、hidden 。

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

2. 什么是 Api 注解 ？

Api 注解是作用在接口類上面的注解，其主要是用來給接口類定義相關(guān)說明。

Api 注解提供了豐富的屬性，來允許我們自定義接口類的描述信息，包括對接口類的簡單描述，接口類所屬的分組等。

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

3. Api 注解主要屬性匯總

4. 屬性詳解

4.1 value() 屬性

定義：

該屬性就是描述接口類的作用是什么，即同一類下的接口都是用來干什么的。

使用方法：

在 Api 注解中聲明 value 的值即可。例如，對于用戶接口類（UserController），我們只需要將 value 的值寫為 ‘user-controller’就好了，這樣我們就能很清楚的知道這個接口類下的所有接口都是用來處理和用戶相關(guān)的請求的，如下代碼段所示（現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點看接口類上使用的注解及屬性即可，下同）。

@Api(value = "user-controller")
public class UserController{
    // do something...
}

代碼解釋：

第1行，我們在 UserController 用戶接口類的上方使用了 @Api 注解的 value 屬性來描述該接口類的作用。

顯示結(jié)果：

可以看到，在 Created by Steafan 下放黑體加粗顯示的 user-Controller 就是我們使用 value 屬性描述的接口類信息了。

Tips ：

1. 通過 value 屬性來對接口類進行描述的這一行為在實際開發(fā)工作中并不常用，各位同學(xué)只需要知道有這么一個 value 屬性就可以了。
2. 在實際開發(fā)工作中， value 屬性經(jīng)常被 tags 屬性所替代，這也是 Swagger 官方所設(shè)定的規(guī)則：當(dāng) Api 注解的 value 屬性和 tags 屬性同時存在時，tags 屬性的值會替代 value 屬性的值，這一點需要同學(xué)們注意。

4.2 tags() 屬性

定義：

該屬性就是對實現(xiàn)相同業(yè)務(wù)功能的接口類做一個大型的分組，該分組中包括同業(yè)務(wù)功能下的所有的接口。

使用方法：

在 Api 注解中聲明 tags 的值即可，如果沒有描述則默認(rèn)值為空。例如，就用戶接口類而言，該接口類屬于用戶業(yè)務(wù)分組，所以我們將 tags 的值描述為‘用戶’或者‘user’，這樣我們就能很清楚的看到這個接口類是屬于用戶業(yè)務(wù)組的，如下代碼段所示。

@Api(tags = {"user"})
public class UserController{
    // do something...
}

代碼解釋：

第1行，我們在 UserController 接口類的上方使用了 @Api 注解的 tags 屬性來描述該接口類所屬的業(yè)務(wù)分組。

顯示結(jié)果：

我們可以看到在 value 屬性的值的位置顯示了 user ，也就是 tags 里寫的 user 了。

上述是 tags 屬性和 value 屬性單獨存在時候的效果，下面我們來看一下 tags 屬性和 value 屬性同時存在的效果，如下代碼段所示：

@Api(value="user-controller", tags = {"user"})
public class UserController{
    // do something...
}

代碼解釋：

第1行，我們在 UserController 接口類的上方使用了 @Api 注解的 value 屬性和 tags 屬性同時來描述該接口類。

顯示結(jié)果：

我們可以看到顯示結(jié)果是和只使用 tags 屬性來描述接口類時相同的結(jié)果，這也證明了 Swagger 官方的設(shè)定。

Tips ： 在實際項目開發(fā)工作中，往往一個業(yè)務(wù)可能包括多個接口類的實現(xiàn)，這種情況需要我們對接口類進行多個分組，而 tags 屬性的類型是字符串類型的數(shù)組，可以描述一個或多個值，如存在多值時，應(yīng)該使用這種方式來描述：@Api(tags = {“user”, “customer”})。

4.3 description() 屬性

定義：

該屬性就是對接口類進行簡單概要的描述，通常是描述一些注意的地方，value 屬性更多的則是描述接口類的用途，這一點同學(xué)們要分清。

使用方法：

在 Api 注解中聲明 description 的值即可，如果沒有描述則默認(rèn)值為空。例如，如果我想添加對用戶接口類的概要描述信息，那么我可以這樣寫 description = “所有用戶業(yè)務(wù)接口必須使用post請求”，如下代碼段所示。

@Api(description = {"所有用戶業(yè)務(wù)接口必須使用post請求"})
public class UserController{
    // do something...
}

代碼解釋：

第1行，我們在 UserController 接口類的上方使用了 @Api 注解的 description 屬性來描述用戶接口類的一些注意的地方和約定。

顯示結(jié)果：

在我用紅框圈起來的地方我們可以看到使用 description 注解所描述的信息了。

Tips ：

1. description 屬性一般用來對接口類進行一些注意事項和約定的描述，不要將其描述為接口類的用途。
2. description 屬性在實際開發(fā)工作中還是很常用的，所以描述好 description 是體現(xiàn)一個程序員對業(yè)務(wù)內(nèi)容是否充分理解的標(biāo)志。

階段小結(jié)（一）

以上是對 Api 注解中經(jīng)常使用的三個屬性進行的詳細(xì)介紹，value，tags，description 這三個屬性不管是在項目開發(fā)中，還是在需求溝通中，使用的都很頻繁，所以真正掌握這三個屬性，是用好 Api 注解的重要前提。在學(xué)習(xí)這三個屬性時，大家應(yīng)該結(jié)合 ApiOperation 注解來對比并總結(jié)它們之間的差異，通過不斷的使用來發(fā)現(xiàn)它們的使用規(guī)律，這一點很重要。

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

4.4 protocols() 和 hidden() 屬性

定義：

protocols() 屬性就是對接口類中，所有的接口所使用的網(wǎng)絡(luò)協(xié)議進行一個約定，常用的網(wǎng)絡(luò)協(xié)議有：http、https。

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

使用方法：

protocols() 屬性默認(rèn)值為空，但是 Swagger 在處理時，會默認(rèn)獲取項目所采用的網(wǎng)絡(luò)協(xié)議，我們可以不用專門設(shè)置，如果一定要設(shè)置該屬性，則只允許設(shè)置http協(xié)議規(guī)定的屬性，不能隨意設(shè)置，http, https 這些都是被允許的。

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

@Api(hidden = true)
public class UserController{
    // do something...
}

代碼解釋：

第1行，我們在 UserController 接口類的上方使用了 @Api 注解的 hidden 屬性來隱藏我們的用戶接口類。

Tips ：

1. 接口類的顯隱控制應(yīng)該根據(jù)特定安全策略和特定客戶需求來決定顯隱，不能無故隱藏接口，更不能頻繁的切換接口的顯隱。
2. 在實際工作中，如果需要隱藏接口類則需要和項目組報備情況，說明原因。

階段小結(jié)（二）

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

5. 小結(jié)

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

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