Swagger-SwaggerDefinition 注解

1. 前言

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

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

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

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

2. 什么是 SwaggerDefinition 注解 ？

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

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

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

3. SwaggerDefinition 注解主要屬性匯總

4. 屬性詳解

4.1 host() 和 basePath() 屬性

定義：

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

basePath 屬性就是描述 swagger-ui 界面的完整訪問地址，他需要依賴 host 屬性。

使用方法：

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

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

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

代碼解釋：

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

顯示結(jié)果：

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

Tips ：

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

4.2 tags() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

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

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

4.3 externalDocs() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第 1 行，我們在 UserController 接口類的上方使用了 @SwaggerDefinition 注解的 externalDocs 屬性來描述額外文檔的地址信息。

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

5. 小結(jié)

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

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