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



io.springfox
springfox-swagger-ui
2.9.2

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

原文地址https://www.cnblogs.com/yichunguo/p/12665857.html

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章