Swagger-Api 注解詳解

1. 前言

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

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

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

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

2. 什么是 Api 注解 ？

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

Api 注解提供了豐富的屬性，來(lái)允許我們自定義接口類的描述信息，包括對(duì)接口類的簡(jiǎn)單描述，接口類所屬的分組等。

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

3. Api 注解主要屬性匯總

4. 屬性詳解

4.1 value() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們?cè)?UserController 用戶接口類的上方使用了 @Api 注解的 value 屬性來(lái)描述該接口類的作用。

顯示結(jié)果：

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

Tips ：

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

4.2 tags() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

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

顯示結(jié)果：

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

上述是 tags 屬性和 value 屬性單獨(dú)存在時(shí)候的效果，下面我們來(lái)看一下 tags 屬性和 value 屬性同時(shí)存在的效果，如下代碼段所示：

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

代碼解釋：

第1行，我們?cè)?UserController 接口類的上方使用了 @Api 注解的 value 屬性和 tags 屬性同時(shí)來(lái)描述該接口類。

顯示結(jié)果：

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

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

4.3 description() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們?cè)?UserController 接口類的上方使用了 @Api 注解的 description 屬性來(lái)描述用戶接口類的一些注意的地方和約定。

顯示結(jié)果：

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

Tips ：

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

階段小結(jié)（一）

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

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

4.4 protocols() 和 hidden() 屬性

定義：

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

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

使用方法：

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

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

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

代碼解釋：

第1行，我們?cè)?UserController 接口類的上方使用了 @Api 注解的 hidden 屬性來(lái)隱藏我們的用戶接口類。

Tips ：

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

階段小結(jié)（二）

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

5. 小結(jié)

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

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