前言
上一篇文章介紹了前後端分離框架，如何設計一個簡單易行的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匹配的這種包含。如
<code>1. `.paths(PathSelectors.ant("/v2/**"))`
/<code>將其限制為某些正則表達式或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中配置了。
<code>1. `spring.mvc.resources.add-mapping:false`
/<code>
將其註釋掉熟悉的界面又回來了，這個配置是不自動給靜態資源添加路徑，導致swagger-ui.html找不到資源。怎麼解決呢？修改一下Swagger2Config
上面的代碼就是人為的把資源做一下映射關係。
源碼Bug坑二
細心的小夥伴在運行時，應用控制檯打印時，會時不時的報異常，如下：
<code>1. `java.lang.NumberFormatException: For input string: ""，出錯的原因呢是因為 空字符串""無法轉成Number。`
/<code>
我們找到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 中加上靜態資源路徑映射即可：
<code>1. `//路徑根據自己的項目去做映射`
2. `registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");`
/<code>
下面介紹企業項目中比較實用的用法
忽略不想生成文檔的接口
某些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則生效
<code>1. `swagger2:`
2. `enable: true(在pro環境下不寫此配置)`
/<code>
配置全局參數
在做前後端分離的項目中，每個接口中都會有相同的參數，如：token，用戶令牌；那怎麼方便的在Swagger中使用呢?我們在Swagger2Config配置類中
上面代碼就達到了在每個接口上面加上了token參數，token是非必填的
總結
今天老顧介紹了swagger的一些實戰，當然介紹了不是太完整，有些網上會有所介紹，老顧只是把一些重點，在這裡闡述了。謝謝！！！
閱讀更多 享學課堂online 的文章
