Swagger-SwaggerDefinition 注解

1. 前言

本節(jié)會(huì)繼續(xù)結(jié)合一個(gè)用戶(hù)接口相關(guān)類(lèi)來(lái)給大家介紹 Swagger 中的另一個(gè)注解 SwaggerDefinition 注解及所提供的常用屬性。

SwaggerDefinition 注解在實(shí)際開(kāi)發(fā)中用的非常少了，盡管他提供了很多屬性，但是在絕大多數(shù)情況下可以通過(guò)配置類(lèi)解決的問(wèn)題都不會(huì)用 SwaggerDefinition 注解。

所以大家在學(xué)習(xí) SwaggerDefinition 注解的時(shí)候，只需要掌握基本定義和基本用法即可，由于篇幅有限，我只會(huì)選取最重要的屬性來(lái)給大家截圖演示，那些基本不用的就不再截圖演示了。

重點(diǎn)講解的屬性：host 、basePath 、tags 、 externalDocs 。

2. 什么是 SwaggerDefinition 注解 ？

SwaggerDefinition 注解是作用在接口類(lèi)上面的注解，其主要是用來(lái)給 Swagger 生成的 UI 界面（下稱(chēng) swagger-ui 界面）做一些額外的描述。

SwaggerDefinition 注解提供了豐富的屬性來(lái)允許我們自定義 swagger-ui 界面的描述信息，包括界面訪問(wèn)地址、界面版本等。

下面我們來(lái)看一下 SwaggerDefinition 注解中都有哪些常用的屬性。

3. SwaggerDefinition 注解主要屬性匯總

4. 屬性詳解

4.1 host() 和 basePath() 屬性

定義：

host 屬性就是描述 swagger-ui 界面的訪問(wèn)主機(jī)，或者說(shuō)是 Ip 地址，即如果，我想訪問(wèn) Swagger 為我們生成的 swagger-ui 界面，所需要在瀏覽器地址欄中輸入的地址信息。

basePath 屬性就是描述 swagger-ui 界面的完整訪問(wèn)地址，他需要依賴(lài) host 屬性。

使用方法：

在 SwaggerDefinition 注解中，聲明 host 和 basePath屬性的值即可。

例如，我想讓 swagger-ui 界面在本地就可以訪問(wèn)，那么我們可以這樣描述 host 屬性： host = “l(fā)ocalhost”, 而 basePath 屬性可以這樣描述： basePath = “l(fā)ocalhost:9001”，這樣我們就能很清楚的知道 swagger-ui 界面所在的位置了（現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點(diǎn)看接口類(lèi)上使用的注解及屬性即可，下同）。

@SwaggerDefinition(host = "localhost", basePath = "localhost:9001")
public class UserController{
    // do something...
}

代碼解釋?zhuān)?/strong>

第 1 行，我們?cè)?UserController 用戶(hù)接口類(lèi)的上方，使用了 @SwaggerDefinition 注解的 host 屬性和 basePath 屬性來(lái)規(guī)定 swagger-ui 界面的生成位置。

顯示結(jié)果：

可以看到，在用紅框圈起來(lái)的地方，就是我們使用 host 屬性和 basePath 屬性所描述的 swagger-ui 界面的訪問(wèn)路徑了。

Tips ：

1. host 屬性和 basePath 屬性的區(qū)別在于：前者只是定義了 swagger-ui 界面的訪問(wèn) Ip 地址，如果沒(méi)有端口的限制，則可以直接訪問(wèn)；而后者則是定義了 swagger-ui 界面的完整位置，其中就包括了端口的存在。
2. 在實(shí)際開(kāi)發(fā)工作中，往往不需要使用這兩個(gè)屬性來(lái)專(zhuān)門(mén)的定義 swagger-ui 的訪問(wèn)路徑，因?yàn)?Swagger 會(huì)默認(rèn)獲取項(xiàng)目中通過(guò)配置類(lèi)來(lái)定義的地址信息，使用這兩個(gè)屬性就多此一舉了。

4.2 tags() 屬性

定義：

該屬性就是對(duì)項(xiàng)目中所有的接口，添加分組類(lèi)型描述，即在全局層面定義接口的所屬分組類(lèi)型，類(lèi)似于 @Api 和 @ApiOperaiton 注解中的 tags 屬性。

使用方法：

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

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

代碼解釋?zhuān)?/strong>

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

Tips ： 該屬性在實(shí)際工作中基本很少使用，如果有的接口需要進(jìn)行分組，那么可以直接使用 @Api 注解的 tags 屬性來(lái)描述，大家只需要知道 SwaggerDefinition 注解存在一個(gè) tags 屬性即可。

4.3 externalDocs() 屬性

定義：

如果接口方法或其中的參數(shù)存在額外的文檔描述，則可以通過(guò)該屬性進(jìn)行綁定，即為接口方法或其中的參數(shù)提供額外的文檔支持。

使用方法：

在 SwaggerDefinition 注解中聲明 externalDocs 的值即可。例如，如果我想添加一個(gè)額外的文檔地址，那么我可以這樣寫(xiě) externalDocs = @ExternalDocs(url = “l(fā)ocalhost:8000”)，如下代碼段所示。

@SwaggerDefinition(externalDocs = @ExternalDocs(url = "localhost:8000"))
public class UserController{
    // do something...
}

代碼解釋?zhuān)?/strong>

第 1 行，我們?cè)?UserController 接口類(lèi)的上方使用了 @SwaggerDefinition 注解的 externalDocs 屬性來(lái)描述額外文檔的地址信息。

Tips ： externalDocs 屬性很少使用，在實(shí)際工作中，如果有的接口方法和接口方法中的參數(shù)有其他額外的描述話，就直接使用 @ApiOperation 來(lái)一并說(shuō)明了，并不會(huì)單獨(dú)使用一個(gè)注解再來(lái)說(shuō)明。

5. 小結(jié)

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

SwaggerDefinition 雖是 Swagger 眾多注解中的一個(gè)注解，但在實(shí)際開(kāi)發(fā)工作中其存在的價(jià)值值得我們重新考量。