SpringBoot整合Springfox-Swagger2

SpringBoot整合Springfox-Swagger2

前言

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

1、Swagger簡介

目前網際網路時代前後端分離已成趨勢，前後端混在一起，前端或者後端無法做到“及時協商，盡早解決”，最終導緻問題集中爆發。解決方案就是前後端通過API進行互動達到相對獨立且松耦合。Swagger就是這樣的一個API架構，Swagger支援多種語言 如：Java，PHP等，它号稱是世界上最流行的API架構！

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

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

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

3、SpringBoot內建Swagger

注意：jdk 1.8以上才能運作swagger2

1、 導入兩個jar包依賴

io.springfox

springfox-swagger2

2.9.2

springfox-swagger-ui

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即可，代碼如下：

public Docket docket1(){

.groupName("組一")
  // 省略配置....           

public Docket docket2(){

.groupName("組二")
 // 省略配置....           

public Docket docket3(){

.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-c0MAgtyOeKx6qzmdUG0w

原文位址

https://www.cnblogs.com/yichunguo/p/12665857.html