前言

　　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

1.首先建立一個基礎的SpringBoot web專案。您可以通過 Spring Initializr 頁面生成一個空的 Spring Boot 專案，或者通過idea建立一個SpringBoot專案

2.新增依賴

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>

3.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());
  }
​
}

4.編寫一些簡單的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";
  }
}

5.驗證程式碼-到這裡我們已經成功整合Swagger2，然後啟動專案，輸入http://localhost:8080/swagger-ui.html，如果能出現下面介面，說明配置成功了。

以上就是本文的全部內容，希望對大家的學習有所幫助，也希望大家多多支援我們。