前言

上一篇文章介紹了前後端分離框架，

如何設計一個簡單易行的API文件

，今天我們就介紹一下

如何在SpringBoot2.x專案中應用此Swagger2框架

，在使用過程中我們需要注意哪些方面。

開始專案

首先，我們需要一個帶有一些Rest Controller的Spring Boot應用程式，我使用了SpringFox 2。9。2和Spring Boot 2。1。12。RELEASE。

新增Swagger2依賴

在pom。xml中加入Swagger2的依賴

建立Swagger2配置類

在專案的配置包下面建立Swagger2的配置類Swagger2Config

配置資訊如下

如上程式碼所示，透過

@Configuration註解，讓Spring來載入該類配置

。

@ EnableSwagger2支援Swagger 2的SpringFox支援。

DocumentationType。SWAGGER_2告訴Docketbean我們正在使用Swagger規範的版本2。

apiInfo（）用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）。

select（）建立一個構建器，用於定義哪些控制器及其生成的文件中應包含哪些方法。

apis（）定義要包含的類（控制器和模型類）。這裡我們包括所有這些，但您可以透過基礎包，類註釋等來限制它們。

SpringFox會將其檢測為文件生成源。Controller和Model類。您可以在Docket配置中輕鬆配置它。我們可以使用。apis（RequestHandlerSelectors。any（）來包含所有類；當然我們也可以縮小到我們的基礎包

paths（）允許您根據路徑對映定義應包含哪個控制器的方法。我們現在包括所有這些，但您可以使用正則表示式等限制它。上面的程式碼。paths（PathSelectors。any（））是代表匹配所有URL。

有時我們還需要

只包含特定的URL路徑

。可能正在使用API的多個版本以實現向後相容，但不希望包含歷史版本。也許API的某些部分是內部的，不應該是公共文件的一部分。無論哪種方式，也可以在Docket中配置基於URL匹配的這種包含。如

將其限制為某些正則表示式或Ant樣式的路徑模式，而不是匹配所有路徑的任何路徑。

將Swagger Core註釋新增到模型類中

我們可以在實體類上面進行註釋

類級別使用@ApiModel註釋

欄位級別@ApiModelProperty

。

@ApiModelProperty的示例對於提供示例值非常有用

，這不僅適用於使用者的指導，而且還可以在使用Swagger UI作為REST客戶端來測試服務時預填充請求有效負載。

Position屬性很方便指定屬性在文件中顯示的順序

。首先提供重要或必需的屬性或屬於一起的組屬性是有用的。否則，屬性將按字母順序列出。

將Swagger Core註釋新增到控制器類

與使用Swagger核心註釋註釋模型類以提供其他元資料相同，您可以註釋控制器及其方法和方法引數。

@Api描述了整個控制器

@ApiOperation用於方法級別的描述

@ApiParam用於方法引數

@ApiImplicitParams、@ApiImplicitParam註解來給引數增加說明

配置到這裡，基本的配置就結束了。那是不是就可以執行啟動。

404坑一

我們在啟動後，請求http：//localhost：8081/swagger-ui。html 直接

報404錯誤

；這個問題是因為我們的專案是純的restful前後端分離的專案，我們在application。yml中配置了。

將其註釋掉熟悉的介面又回來了，這個配置是不自動給靜態資源新增路徑，導致swagger-ui。html找不到資源。怎麼解決呢？修改一下Swagger2Config

上面的程式碼就是人為的把資源做一下對映關係。

原始碼Bug坑二

細心的小夥伴在執行時，應用控制檯列印時，會時不時的報異常，如下：

我們找到Swagger包下丟擲異常的類：

這個異常就是因為上面原始碼上面的判斷條件有問題，如果example屬性不配置的話，在屬性是Integer型別時Long。valueOf（example）時就會報異常，解決方法：

io。springfox：springfox-swagger2：2。9。2中依賴了

swagger-models的1.5.20版本

，我們可以

排除springfox-swagger2中的swagger-models依賴

，匯入

io.swagger:swagger-models的1.5.21版本

即可

靜態資源404坑三

到現在為止，如果應用是一個純粹的 REST Api 介面服務，那就基本沒什麼問題，但如果應用中仍然有檢視模板、靜態資源時，可能就會出現載入不到靜態資源了。如果出現這個問題，那隻要在Swagger配置類 SwaggerConfig 中加上靜態資源路徑對映即可：

下面介紹企業專案中比較實用的用法

忽略不想生成文件的介面

某些Controller 不需要生成API文件的介面，可以透過@ApiIgnore忽略掉

生產環境關閉Swagger

swagger用來在開發階段方便前後端開發。降低交流成本。但是版本上線之後，需要把swagger關閉。

在配置類Swagger2Config中加上條件註解

透過@ConditionalOnProperty（prefix = “swagger2”，value = {“enable”}，havingValue = “true”）註解實現。

讀取配置檔案中字首為swagger2的配置，屬性名為enable，值為true。

當條件成立，此配置類被啟用。

兩個屬性name以及havingValue，其中name用來從application。properties中讀取某個屬性值，

如果該值為空，則返回false;

如果值不為空，

則將該值與havingValue指定的值進行比較

，如果一樣則返回true；否則返回false。如果返回值為false，

則該configuration不生效；為true則生效

配置全域性引數

在做前後端分離的專案中，每個介面中都會有相同的引數，如：token，使用者令牌；那怎麼方便的在Swagger中使用呢？我們在Swagger2Config配置類中

上面程式碼就達到了在每個介面上面加上了token引數，token是非必填的

總結

今天老顧介紹了swagger的一些實戰，當然介紹了不是太完整，有些網上會有所介紹，老顧只是把一些重點，在這裡闡述了。謝謝！！！