SpringBoot 集成 Swagger-UI 詳解

1. 前言

本套課程主要針對 Swagger-UI 在 SpringBoot 開發(fā)框架中的使用，本節(jié)內(nèi)容是學(xué)習(xí)本套課程的開端。

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

重點(diǎn)講解內(nèi)容：

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

• 集成過程中的一些經(jīng)驗(yàn)和注意事項(xiàng)、Swagger-UI 不同版本與 SpringBoot 框架兼容問題。

2. SpringBoot 集成 Swagger-UI 的準(zhǔn)備工作

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

所以當(dāng)我們需要在項(xiàng)目中集成某種工具時(shí)，我們需要將該工具對應(yīng)的坐標(biāo)放到 Maven 的 pom.xml 文件中去。

通過訪問 Maven 的中央倉庫我們可以搜索到 Swagger-UI 對應(yīng) SpringBoot 框架適合的坐標(biāo)數(shù)據(jù)，如下 Maven 坐標(biāo)所示：

<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 坐標(biāo)中，第一個(gè) springfox-swagger2 依賴，為 Swagger 2 的核心依賴，即我們?nèi)绻胧褂?Swagger 工具，則必須要在項(xiàng)目中引入該依賴，如果我們沒有引入該依賴，那么我們是不能在項(xiàng)目中使用 Swagger 的。

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

在將上述兩個(gè) Swagger 的坐標(biāo)數(shù)據(jù)放到我們項(xiàng)目的 pom.xml 文件中去之后，我們就完成了集成 Swagger-UI 的準(zhǔn)備工作。

這樣引入的 Swagger-UI 我們只能使用它的注解，而這時(shí)所產(chǎn)生的 Swagger-ui 界面我們是看不懂的，因?yàn)槲覀冞€沒有對界面增加我們的規(guī)定，所以接下來讓我們完成 Swagger-UI 的一些基本配置。

3. 在 SpringBoot 中配置 Swagger-UI

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

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

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

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

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

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

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

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

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

Tips：

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

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

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

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

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

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

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

4. Swagger-UI 配置類詳解

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

創(chuàng)建 Swagger 應(yīng)用配置：

代碼解釋：

createRestApi 方法的返回值是一個(gè) Docket 類型，該類型就是返回 Swagger-Documentation 類型的數(shù)據(jù)，大家不用關(guān)心。

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

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

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

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

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

創(chuàng)建 Swagger-UI 界面基本信息配置：

代碼解釋：

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

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

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

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

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

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

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

Tips:

1. 訪問路徑中的 swagger-ui.html 為默認(rèn)固定寫法，一般不用修改。
2. createRestApi() 方法為 public 方法，即這個(gè)方法需要對外暴露才行，而 apiInfo() 方法為 private 私有方法；該方法的用途是配置 Swagger-UI 界面基本信息，只能在項(xiàng)目中進(jìn)行配置，不能將配置權(quán)限暴露出去。
3. 在 apiInfo() 方法中我們不需要寫太多的信息，因?yàn)橐恍┍匾男畔⒍际窃诮涌谥衼砻枋龅摹?/li>

5. 小結(jié)

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

針對 Swagger-UI 界面上的每一個(gè)組成元素在這里就不系統(tǒng)介紹了，后面會有專門的小節(jié)來對 Swagger-UI 界面的組成元素以及如何使用 Swagger-UI 進(jìn)行簡單必要的接口調(diào)試進(jìn)行系統(tǒng)性地詳細(xì)介紹，請各位同學(xué)關(guān)注。