前言

不管Spring Boot整合還是SpringMVC整合Swagger都基本類似，重點就在於配置Swagger，它的精髓所在就在於配置。
@

• 1、Swagger簡介
• 2、整合前可能遇到的問題
• 3、SpringBoot整合Swagger
• 4、配置Swagger
  • 4.1、Swagger四部分佈局
  • 4.2、第二部分：API基本資訊
    • 1、分析
    • 2、RequestHandlerSelectors過濾
  • 4.3、第一部分：配置API分組
  • 4.4、Swagger2的常用註解
  • 4.5、第三部分：API請求列表
  • 4.6、第四部分：API實體列表

1、Swagger簡介

目前網際網路時代前後端分離已成趨勢，前後端混在一起，前端或者後端無法做到“及時協商，儘早解決”，最終導致問題集中爆發。解決方案就是前後端通過API進行互動達到相對獨立且鬆耦合。Swagger

2、整合前可能遇到的問題

1、
匯入好依賴jar包之後，使用註解說找不到之類的問題，如遇到，請參考：所有Intellij IDEA Cannot Resolve Symbol XXX問題的解決方法彙總

2、
版本問題，SpringBoot的版本很多，被整合的框架版本也很多，可能版本高一點或者低一點就可能出現各種bug，這是整合其他框架的通病，這裡得注意一下。如果執行出現一些什麼bug，如果對SpringBoot底層原理不是很瞭解的可以先百度谷歌一下，找不到建議不妨換個SpringBoot的版本！

3、SpringBoot整合Swagger

注意：jdk 1.8以上才能執行swagger2

1、
匯入兩個jar包依賴

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
 

2、
要想使用Swagger，必須編寫一個配置類來配置 Swagger，這裡的配置類如下

@Configuration //說明這是一個配置類
@EnableSwagger2// 該註解開啟Swagger2的自動配置
public class SwaggerConfig {  //隨便的一個類名

}

3、
這個時候已經算是初步整合完畢了，啟動專案可訪問http://localhost:8080/swagger-ui.html 可以看到swagger的介面，如下；

4、配置Swagger

不管是Spring Boot整合還是SpringMVC整合Swagger都基本類似，重點就在於配置Swagger，它的精髓所在就在於配置，這很關鍵。我們從下圖來全域性看看Swagger的四部分重點佈局：

4.1、Swagger四部分佈局

Swagger例項Bean是Docket，所以必須通過配置Docket例項來配置Swaggger。

第一部分--API分組：如果沒有配置分組預設是default。通過Swagger例項Docket的groupName()方法即可配置分組
第二部分--基本描述：可以通過Swagger例項Docket的apiInfo()方法中的ApiInfo例項引數配置文件資訊
第三部分--請求介面列表：在組範圍內，只要被Swagger2掃描匹配到的請求都會在這裡出現。
第四部分--實體列表：只要實體在請求介面的返回值上（即使是泛型），都能對映到實體項中！

第四部分注意：並不是因為@ApiModel註解讓實體顯示在Models列表裡，而是隻要出現在介面方法的返回值上的實體都會顯示在這裡，而@ApiModel和@ApiModelProperty這兩個註解只是為實體添加註釋的。前者為類添加註釋，後者為類屬性添加註釋。

4.2、第二部分：API基本資訊

先從第二部分開始分析，這樣分析對理解第一部分比較有幫助。

@Configuration
@EnableSwagger2
@ComponentScan("com.yichun.swagger_boot_demo.controller")
public class SwaggerConfig {
    @Bean
    public Docket docker(){
        // 建構函式傳入初始化規範，這是swagger2規範
        return new Docket(DocumentationType.SWAGGER_2)
                //apiInfo： 新增api詳情資訊，引數為ApiInfo型別的引數，這個引數包含了第二部分的所有資訊比如標題、描述、版本之類的，開發中一般都會自定義這些資訊
                .apiInfo(apiInfo())
                .groupName("yichun123")
                //配置是否啟用Swagger，如果是false，在瀏覽器將無法訪問，預設是true
                .enable(true) 
                .select()
                //apis： 新增過濾條件,
                .apis(RequestHandlerSelectors.basePackage("com.yichun.swagger_boot_demo.controller"))
                //paths： 這裡是控制哪些路徑的api會被顯示出來，比如下方的引數就是除了/user以外的其它路徑都會生成api文件
                .paths((String a) ->
                        !a.equals("/user"))
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("名字：name", "個人連結：http://xxx.xxx.com/", "郵箱：XXX");
        return new ApiInfo(
                      "標題內容", // 標題
                      "描述內容", // 描述
                      "版本內容：v1.0", // 版本
                      "連結：http://terms.service.url/", // 組織連結
                       contact, // 聯絡人資訊
                      "許可：Apach 2.0 ", // 許可
                      "許可連結：XXX", // 許可連線
                      new ArrayList<>()// 擴充套件
        );
    }
}

1、分析

2、RequestHandlerSelectors過濾

點進RequestHandlerSelectors原始碼，分析如下：

4.3、第一部分：配置API分組

實際上，上面的內容就是一個完整的API組

1、配置一個分組
我們之前說過，如果沒有配置分組預設是default。通過Swagger例項Docket的groupName()方法即可配置分組，程式碼如下：

@Bean
public Docket docket2(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo()) // 配置基本API資訊
      .groupName("hello") // 配置分組
       // 省略配置....
}

2、如何配置多個分組
很簡單，配置多個分組只需要配置多個docket即可，程式碼如下：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2)
      .groupName("組一")
      // 省略配置....
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2)
     .groupName("組二")
     // 省略配置....
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2)
     .groupName("組三")
     // 省略配置....
}

4.4、Swagger2的常用註解

講第三部分和第四部分前，非常有必要先了解swagger2的常用註解，用註解的話，可以給一些比較難理解的屬性或者介面，增加一些配置資訊，讓人更容易閱讀！這點也是swagger2的重中之重！

首先我們得知道一點Swagger的所有註解定義在io.swagger.annotations包下。，這裡只列出一些常用的註解，如下：

如果要詳細瞭解這些註解可以參考swagger2 註解說明

4.5、第三部分：API請求列表

請求介面列表：在組範圍內，只要被Swagger2掃描匹配到的請求都會在這裡出現。使用註解能更好的提高閱讀性。

4.6、第四部分：API實體列表

之前說過，只要實體在請求介面的返回值上（即使是泛型），都能對映到實體項中！是的，因此我們第一步是先有實體類。

1、
我們先隨便建立一個實體類

@ApiModel("使用者實體類")
public class User {
    
    @ApiModelProperty("性別")
    public String sex;

    @ApiModelProperty(value ="使用者名稱",allowableValues = "11,12")
    public int name;  
}

當然@ApiModelProperty註解裡有很多屬性，也會有許多坑，這裡注意一下，本篇文章暫不概述。

2、
只要這個實體在請求介面的返回值上（包括泛型），都能對映到實體項中，所以我們編寫程式碼如下：

 @GetMapping("/User2")
 public User getUser2(){
 
    return new User();
 }

效果如下：

本篇文章非常淺顯，若有不正之處，歡迎批評指正，感激不盡！

歡迎各位關注我的公眾號，裡面有一些java學習資料和一大波java電子書籍，比如說周志明老師的深入java虛擬機器、java程式設計思想、核心技術卷、大話設計模式、java併發程式設計實戰.....都是java的聖經，不說了快上Tomcat車，咋們走！最主要的是一起探討技術，嚮往技術，追求技術，說好了來了就是盆友喔...

參考：https://mp.weixin.qq.com/s/0-c0MAgtyOeKx6qzmdU