前言 Spring Boot 框架是目前非常流行的微服務框架，我們很多情況下使用它來提供 Rest API。而對於 Rest API 來說很重要的一部分內容就是文檔，Swagger 為我們提供了一套通過代碼和註解自動生成文檔的方法，這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Sw ...
前言
Spring Boot 框架是目前非常流行的微服務框架，我們很多情況下使用它來提供 Rest API。而對於 Rest API 來說很重要的一部分內容就是文檔，Swagger 為我們提供了一套通過代碼和註解自動生成文檔的方法，這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規範的 Springfox 實現來瞭解如何在 Spring Boot 項目中使用 Swagger，主要包含瞭如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和註解。
Swagger 簡介
Swagger 是一套基於 OpenAPI 規範構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了以下三個部分：
-
Swagger Editor：基於瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規範。
-
Swagger UI：它會將我們編寫的 OpenAPI 規範呈現為互動式的 API 文檔，後文我將使用瀏覽器來查看並且操作我們的 Rest API。
-
Swagger Codegen：它可以通過為 OpenAPI（以前稱為 Swagger）規範定義的任何 API 生成伺服器存根和客戶端 SDK 來簡化構建過程。
為什麼要使用 Swagger
當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式，下麵我們就來瞭解一下它的優點：
-
代碼變，文檔變。只需要少量的註解，Swagger 就可以根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。
-
跨語言性，支持 40 多種語言。
-
Swagger UI 呈現出來的是一份可互動式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用，省去了準備複雜的調用參數的過程。
-
還可以將文檔規範導入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創建自動化測試。
以上這些優點足以說明我們為什麼要使用 Swagger 了，您是否已經對 Swagger 產生了濃厚的興趣了呢？下麵我們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger，讓我們從準備一個 Spring Boot 的 Web 項目開始吧。
SpringBoot整合Swagger2
-
首先創建一個基礎的SpringBoot web項目。您可以通過 Spring Initializr 頁面生成一個空的 Spring Boot 項目，或者通過idea創建一個SpringBoot項目
-
添加依賴
- Spring Boot 的 Web 依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
- 集成swagger2
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
- 集成Swagger UI
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
- Spring Boot 的 Web 依賴
-
java中Swagger2配置-直接上配置代碼，Swagger2的配置是比較容易的，在成功項目創建之後，只需要開發者自己提供一個Docket的Bean。（註釋寫的很清楚，這裡就不一一解釋了。不懂的地方可以在片尾關註我公眾號加我WX。）
/** * 集成swagger2 解決前後端分離 弊端：不能及時協商+今早解決的問題 * 使用swagger總結: * 通過swagger 給一些比基奧難理解的介面或屬性，增加註釋信息 * 介面文檔實時更新 * 可以線上測試 * 安全問題: * 正式上線的時候 記得關閉swagger */ @Configuration//載入到springboot配置裡面 @EnableSwagger2//開啟swagger2 public class SwaggerConfig { /** * 配置swagger2 * 註冊一個bean屬性 * swagger2其實就是重新寫一個構造器，因為他沒有get set方法\ * enable() 是否啟用swagger false swagger不能再瀏覽器中訪問 * groupName()配置api文檔的分組 那就註冊多個Docket實例 相當於多個分組 * @return */ @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("XXX")//組名稱 .enable(true) .select() /** * RequestHandlerSelectors配置掃描介面的方式 * basePackage 配置要掃描的包 * any 掃描全部 * none 不掃描 * withClassAnnotation 掃描類上的註解 * withMethodAnnotation 掃描方法上的註解 */ .apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller")) /** * paths() 掃描過濾方式 * any過濾全部 * none不過濾 * regex正則過濾 * ant過濾指定路徑 */ // .paths(PathSelectors.ant("/login/**")) .build(); } /** * 配置swagger2信息 =apiInfo * @return */ public ApiInfo apiInfo(){ /*作者信息*/ // Contact contact = new Contact("XXX", "http://baidu.com", "email"); Contact contact = new Contact("", "", ""); return new ApiInfo( "XXX的API介面", "company介面", "V1.0", "urn:toVs", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
- 編寫一些簡單的java介面。（你可以根據你的情況進行編寫）
@Api(tags = "TestController測試") @RestController public class TestController { @ApiOperation("login api") @GetMapping("/") public String login() { return "Hello login ~"; } @ApiOperation("helloWord Api") @GetMapping("/index") public String index() { return "Hello World ~"; } @ApiOperation("admin Api") @GetMapping("/admin/hello") public String admin() { return "hello admin!"; } @ApiOperation("user Api") @GetMapping("/user/hello") public String user() { return "hello user"; } }
- 驗證代碼-到這裡我們已經成功集成Swagger2，然後啟動項目，輸入http://localhost:8080/swagger-ui.html，如果能出現下麵界面，說明配置成功了。
- 未完待續。下章節講解Swagger的常用註解。
這篇文章是否幫助到你呢？掃描關註公眾號--【Madison龍少】，【Madison龍少】公眾號每天提供java乾貨，乾貨滿滿。
