Swagger-SwaggerDefinition 注解

1. 前言

本節會繼續結合一個用戶接口相關類來給大家介紹 Swagger 中的另一個注解 SwaggerDefinition 注解及所提供的常用屬性。

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

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

重點講解的屬性：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 界面的訪問主機，或者說是 Ip 地址，即如果，我想訪問 Swagger 為我們生成的 swagger-ui 界面，所需要在瀏覽器地址欄中輸入的地址信息。

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

使用方法：

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

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

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

代碼解釋：

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

顯示結果：

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

Tips ：

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

4.2 tags() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

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

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

4.3 externalDocs() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

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

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

5. 小結

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

SwaggerDefinition 雖是 Swagger 眾多注解中的一個注解，但在實際開發工作中其存在的價值值得我們重新考量。