SpringBoot 集成 Swagger-UI 詳解

1. 前言

本套課程主要針對 Swagger-UI 在 SpringBoot 開發框架中的使用，本節內容是學習本套課程的開端。

在本節中將為大家介紹如何使用 SpringBoot 來集成 Swagger-UI ，包括集成 Swagger-UI 的具體詳細步驟，以及在集成過程中的一些注意事項。

重點講解內容：

• SpringBoot 主流開發框架與 Swagger-UI 工具的集成步驟。

• 集成過程中的一些經驗和注意事項、Swagger-UI 不同版本與 SpringBoot 框架兼容問題。

2. SpringBoot 集成 Swagger-UI 的準備工作

我們知道，使用 Maven 來創建的項目會有專門的一個 pom.xml 文件，這個文件是我們項目中所有用到的工具包的一個列表，在 java 中被稱作 jar 包。在 Maven 中通過引入不同的 jar 包坐標配置來將相應的工具集成到我們的項目中。

所以當我們需要在項目中集成某種工具時，我們需要將該工具對應的坐標放到 Maven 的 pom.xml 文件中去。

通過訪問 Maven 的中央倉庫我們可以搜索到 Swagger-UI 對應 SpringBoot 框架適合的坐標數據，如下 Maven 坐標所示：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
</dependency>

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
</dependency>

在上述 Maven 坐標中，第一個 springfox-swagger2 依賴，為 Swagger 2 的核心依賴，即我們如果想使用 Swagger 工具，則必須要在項目中引入該依賴，如果我們沒有引入該依賴，那么我們是不能在項目中使用 Swagger 的。

而 springfox-swagger-ui 這一依賴，就是我們本文所介紹的 Swagger-UI 的依賴，如果我們不引入該依賴，我們是不會看到 Swagger 的 API 管理界面的。

在將上述兩個 Swagger 的坐標數據放到我們項目的 pom.xml 文件中去之后，我們就完成了集成 Swagger-UI 的準備工作。

這樣引入的 Swagger-UI 我們只能使用它的注解，而這時所產生的 Swagger-ui 界面我們是看不懂的，因為我們還沒有對界面增加我們的規定，所以接下來讓我們完成 Swagger-UI 的一些基本配置。

3. 在 SpringBoot 中配置 Swagger-UI

由于 SpringBoot 框架簡化了傳統 Spring MVC 框架中繁瑣的 xml 文件配置，所以我們在對 Swagger-UI 進行配置時只需要使用兩個注解和一個配置類即可完成，SpringBoot 為我們提供了兩種配置方法，讓我們來看一下吧。

Tips : 在接下來的兩種配置方法中，主要介紹 Swagger-UI 的集成注解，而對于配置類我會單獨進行詳細講解，請同學們注意。

3.1 第一種方式 Swagger-UI 集成注解與配置類分開配置

Swagger-UI 官方針對 SpringBoot 框架推出了很方便的開放 API ，我們在引入了 Swagger-UI 的 Maven 坐標之后，只需要在 SpringBoot 應用的啟動類的上方加入開啟 Swagger-UI 的注解即可在項目中來使用 Swagger-UI。

在上圖中，我添加了 @EnableSwagger2 注解，這正是 Swagger-UI 官方在 SpringBoot 框架中提供的開啟使用 Swagger-UI 的注解。

當我們在項目的啟動類上方添加了 @EnableSwagger2 注解之后就表示我們可以在項目中來使用 Swagger-UI 了。

Tips : 如果我們只引入了 Swagger-UI 的依賴，沒有配置 @EnableSwagger2 注解，那么在項目中我們也是無法使用 Swagger-UI 的，這一點需要同學們特別注意。

對于 Swagger-UI 的配置類來說，我們只需要新建一個配置類并將該配置類通過添加 @Configuration 注解來注入到我們的項目中即可。

以上是配置 Swagger-UI 的第一種方法，即通過 @EnableSwagger2 注解與 @Configuration 注解相分離的方式來配置，這種配置方式相對來說好理解一些。

Tips：

1. 各位同學在集成 Swagger-UI 時，依賴的版本請務必和老師保持一致，避免由于版本原因而出現的未知問題。
2. SpringBoot 框架版本請選擇 SpringBoot 2.0.X.RELEASE 及以上版本或 SpringBoot 的里程碑版本。
3. @Configuration 注解貫穿整個 SpringBoot 框架，有不懂的同學請自行了解。

3.2 第二種方式 Swagger-UI 集成注解與配置類集中配置

在第一種方式中我們將兩個注解進行了分開配置，這種方法通俗易懂，而在本方式中，會將兩個注解集中來配置。

我們新建一個類，名為 Swagger2Config ，這個類就是我們后續要講的 Swagger-UI 配置類了，然后我們在該類的最上方添加上述兩個注解：

在上圖中，我們通過在啟動類中添加 @Configuration 注解的方式將配置類以及 Swagger-UI 的所有注解來一起注入到我們項目中去，這與第一種方式的不同之處在于：

第一種方式， @EnableSwagger2 注解的聲明沒有通過 @Configuration 注解來處理，而是通過 SpringBoot 應用去自動裝配；第二種方式則是將配置類和 Swagger-UI 的所有注解都通過 @Configuration 注解來處理，不通過 SpringBoot 應用去自動裝配。

而上述兩種方式并不會影響項目的正常運行，所以我們采用任何一種方式都是可取的。

4. Swagger-UI 配置類詳解

在本部分中，老師將帶領大家針對 Swagger-UI 常用的基本配置屬性以及其他額外屬性進行詳細講解，下面我們來看一下 Swagger-UI 都需要在 SpringBoot 框架中配置哪些屬性（所有屬性都根據官方配置演變而來）。

創建 Swagger 應用配置：

代碼解釋：

createRestApi 方法的返回值是一個 Docket 類型，該類型就是返回 Swagger-Documentation 類型的數據，大家不用關心。

在方法內部，使用匿名內部類的方式實例化了一個 Docket 對象并返回，DocumentationType 即文檔類型的選擇我們需要根據集成的 Swagger 的版本來選擇，這里選擇 SWAGGER_2 表示使用的 Swagger 是2.X系列版本。

apiInfo() 和 select() 這兩個方法是配置 Swagger 應用的必要方法，我們只需要這樣理解就可以了：集成必要的 API 信息（apiInfo() 方法）來供我們查詢（select() 方法）使用。

apis() 方法里面通過 RequestHandlerSelectors.basePackage() 屬性來描述我們的目標包，就是我們項目中接口所在包的完整目錄名稱，這樣 Swagger 就可以掃描到了，如果不配置此項，Swagger 是掃描不到我們項目中的接口的。

paths() 方法就是規定將我們項目中所有接口的請求路徑都暴露給 Swagger 來生成 Swagger-UI 界面。

build() 方法就是將我們設置的上述參數都放到返回的 Docket 實例中。

創建 Swagger-UI 界面基本信息配置：

代碼解釋：

apiInfo 方法返回 Swagger-ApiInfo 類型，大家可以理解為返回 Swagger-UI 界面的基本信息就行了。在方法內部也是通過匿名內部類的方式返回一個 ApiInfo 實例。

title() 方法：就是來規定我們的 Swagger-UI 界面的大標題。

description() 方法：就是來規定對 Swagger-UI 界面的一些簡單描述信息。

contact() 方法：就是來規定創建 Swagger-UI 的作者的名稱，目前已被廢棄。

version() 方法：就是來規定 Swagger-UI 界面上所有接口的版本。

build() 方法：就是將我們設置的上述參數都放到返回的 ApiInfo 實例中。

通過上述兩個方法的配置，我們就完成了 Swagger-UI 的基本配置，啟動項目之后，在瀏覽器地址欄中輸入訪問路徑（一般為項目 ip 地址：端口/swagger-ui.html）就可以在瀏覽器中看到 Swagger-UI 的界面效果了。

Tips:

1. 訪問路徑中的 swagger-ui.html 為默認固定寫法，一般不用修改。
2. createRestApi() 方法為 public 方法，即這個方法需要對外暴露才行，而 apiInfo() 方法為 private 私有方法；該方法的用途是配置 Swagger-UI 界面基本信息，只能在項目中進行配置，不能將配置權限暴露出去。
3. 在 apiInfo() 方法中我們不需要寫太多的信息，因為一些必要的信息都是在接口中來描述的。

5. 小結

本小節從 Swagger-UI 集成準備工作開始，到不同的配置集成方式，再到最后對 Swagger 配置類的詳細闡述，從零到一的對 SpringBoot 如何集成 Swagger-UI 進行了詳細的講解，旨在幫助大家能夠準確的集成 Swagger-UI ，對于在集成中容易出現的問題，老師也做了相應的提醒和解決建議，希望各位同學都能成功在 SpringBoot 中集成 Swagger-UI。

針對 Swagger-UI 界面上的每一個組成元素在這里就不系統介紹了，后面會有專門的小節來對 Swagger-UI 界面的組成元素以及如何使用 Swagger-UI 進行簡單必要的接口調試進行系統性地詳細介紹，請各位同學關注。