Spring Boot 2.0 整合Swagger2開發RESTful風格的Web服務

摘要： 很多開發人員都不喜歡寫文件！在他們根深蒂固的觀念中，寫文件就是浪費時間，還不如直接寫程式碼酣暢淋漓的痛快！尤其是對於 Java 後臺開發人員而言，維護一份介面文件，更是一件痛不欲生的事情！介面太多了，變化太多了，改完程式碼還要改文件。流程不規範的團隊，經常會出現這樣的情況：有時候介面程式碼變...

很多開發人員都不喜歡寫文件！在他們根深蒂固的觀念中，寫文件就是浪費時間，還不如直接寫程式碼酣暢淋漓的痛快！尤其是對於 Java 後臺開發人員而言，維護一份介面文件，更是一件痛不欲生的事情！介面太多了，變化太多了，改完程式碼還要改文件。流程不規範的團隊，經常會出現這樣的情況：有時候介面程式碼變了，文件沒有及時更新，前端開發人員不知道；有時候是後臺開發人員直接與前端開發人員私下商量一致，直接更新程式碼不更新文件，久而久之，文件就是去了作用，成了擺設。另外，介面測試工作要藉助類似 Postman 的第三方工具。但事與人違，文件是交流溝通的媒介，文件是專案驗收的必備材料，文件是知識和經驗的積累！每一個開發人員無法避免的一項工作，就是寫文件！

那麼，有沒有什麼工具能夠幫助我們自動生成介面文件呢？懶人自有天助吧！ Swagger 幫助我們解決以上困惑。 Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化  RESTful  風格的  Web  服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。在 Spring Boot 專案中，可以將檔案的方法、引數和模型緊密整合到伺服器端的程式碼，允許 API 來始終保持同步。 Swagger 作用主要包括兩點：介面文件線上自動生成和功能測試。

下面，我們來詳細介紹 Spring Boot 2.0  整合  Swagger2 流程：

第一步， 新建工程，在 POM 中新增 Swagger2 依賴，版本是 2.9.2 ， Spring Boot 版本 2.0.6 RELEASE 。 spring-boot-starter-web 提供了 Spring MVC 的支援。如下圖所示：

第二步， 編寫啟動類，在類上使用 @SpringBootApplication 和 @EnableSwagger2 註解，並使用 @Bean 註解例項化一個 Docket 的 Bean 。為方便開發使用， @SpringBootApplication 內部是整合了 @Configuration、 @EnableAutoConfiguration 和 @ComponetScan 註解，並開啟了 Spring Boot 程式的元件掃描和自動配置功能。其中， @Configuration 是將 Swagger2 與 Spring Boot 專案進行整合的關鍵註解。

第三步， 至此， Swagger2 可以與 Spring Boot 專案一起工作了。執行專案，在瀏覽器中訪問 URL（localhost:8080/v2/api-docs） ，驗證效果如下圖所示：

第四步， 問題接踵而至。第三步訪問 URL 執行結果是一堆 JSON 串，非常生澀難懂，不具有人性化。慶幸的是， Swagger2 提供了 UI 互動的解決方案，在 POM 中新增 Swagger2 UI 依賴。如下圖：

第五步， 執行專案，在瀏覽器中訪問 URL(localhost:8080/swagger-ui.html) ，驗證效果如下圖所示：

第六步， 新建 SwaggerController 類，提供 RESTFul 服務，如下圖所示：

第七步， 執行專案，在瀏覽器中訪問 URL(localhost:/swagger-ui.html) ，點選 “Try it out！” 按鈕，可以進行服務介面測試。驗證效果如下圖所示：​

結束語：綜上所述，相比為介面編寫文件的工作，我們增加的配置內容是非常少而且精簡的，對於原有程式碼的影響也在忍受範圍之內。因此，在構建RESTful API的同時，加入Swagger2來對API文件進行管理，是個不錯的選擇。