Swagger基于SpringBoot實作

學習目标：

了解Swagger的概念及作用

掌握在項目中內建Swagger自動生成API文檔

Swagger簡介

前後端分離

前端 -> 前端控制層、視圖層

後端 -> 後端控制層、服務層、資料通路層

前後端通過API進行互動

前後端相對獨立且松耦合

産生的問題

前後端內建，前端或者後端無法做到“及時協商，盡早解決”，最終導緻問題集中爆發

解決方案

首先定義schema [ 計劃的提綱 ]，并實時跟蹤最新的API，降低內建風險

Swagger

号稱世界上最流行的API架構

Restful Api 文檔線上自動生成器 => API 文檔 與API 定義同步更新

直接運作，線上測試API

支援多種語言 （如：Java，PHP等）

官網：https://swagger.io/

SpringBoot內建Swagger

SpringBoot內建Swagger => springfox，兩個jar包

Springfox-swagger2

swagger-springmvc
           

使用Swagger

要求：jdk 1.8 + 否則swagger2無法運作

步驟：

1、建立一個SpringBoot-web項目

2、添加Maven依賴

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

3、編寫HelloController，測試確定運作成功！

4、要使用Swagger，我們需要編寫一個配置類-SwaggerConfig來配置 Swagger

@Configuration //配置類
@EnableSwagger2// 開啟Swagger2的自動配置
public class SwaggerConfig {  
}
           

5、通路測試 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

配置Swagger

1、Swagger執行個體Bean是Docket，是以通過配置Docket執行個體來配置Swaggger。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2);
}
           

2、可以通過apiInfo()屬性配置文檔資訊

//配置文檔資訊
private ApiInfo apiInfo() {
   Contact contact = new Contact("聯系人名字", "http://xxx.xxx.com/聯系人通路連結", "聯系人郵箱");
   return new ApiInfo(
           "Swagger學習", // 标題
           "學習示範如何配置Swagger", // 描述
           "v1.0", // 版本
           "http://terms.service.url/組織連結", // 組織連結
           contact, // 聯系人資訊
           "Apach 2.0 許可", // 許可
           "許可連結", // 許可連接配接
           new ArrayList<>()// 擴充
  );
}
           

3、Docket 執行個體關聯上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
           

4、重新開機項目，通路測試 http://localhost:8080/swagger-ui.html 看下效果；

配置掃描接口

1、建構Docket時通過select()方法配置怎麼掃描接口。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
      .build();
}
           

2、重新開機項目測試，由于我們配置根據包的路徑掃描接口，是以我們隻能看到一個類

3、除了通過包路徑配置掃描接口外，還可以通過配置其他方式掃描接口，這裡注釋一下所有的配置方式：

any() // 掃描所有，項目中的所有接口都會被掃描到
none() // 不掃描接口
// 通過方法上的注解掃描，如withMethodAnnotation(GetMapping.class)隻掃描get請求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通過類上的注解掃描，如.withClassAnnotation(Controller.class)隻掃描有controller注解的類中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根據包路徑掃描接口
           

4、除此之外，我們還可以配置接口掃描過濾：

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通過path過濾,即這裡隻掃描請求以/kuang開頭的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
           

5、這裡的可選值還有

any() // 任何請求都掃描
none() // 任何請求都不掃描
regex(final String pathRegex) // 通過正規表達式控制
ant(final String antPattern) // 通過ant()控制
           

配置Swagger開關

1、通過enable()方法配置是否啟用swagger，如果是false，swagger将不能在浏覽器中通路了

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(false) //配置是否啟用Swagger，如果是false，在浏覽器将無法通路
      .select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通過path過濾,即這裡隻掃描請求以/kuang開頭的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
           

2、如何動态配置當項目處于test、dev環境時顯示swagger，處于prod時不顯示？

@Bean
public Docket docket(Environment environment) {
   // 設定要顯示swagger的環境
   Profiles of = Profiles.of("dev", "test");
   // 判斷目前是否處于該環境
   // 通過 enable() 接收此參數判斷是否要顯示
   boolean b = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(b) //配置是否啟用Swagger，如果是false，在浏覽器将無法通路
      .select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通過path過濾,即這裡隻掃描請求以/kuang開頭的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}
           

3、可以在項目中增加一個dev的配置檔案檢視效果！

通過這個spring.profiles.active 開關觀察swagger是否啟用

配置API分組

1、如果沒有配置分組，預設是default。通過groupName()方法即可配置分組：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分組
       // 省略配置....
}
           

2、重新開機項目檢視分組

3、如何配置多個分組？配置多個分組隻需要配置多個docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
           

4、重新開機項目檢視即可

實體配置

1、建立一個實體類

@ApiModel("使用者實體")
public class User {
   @ApiModelProperty("使用者名")
   public String username;
   @ApiModelProperty("密碼")
   public String password;
}
           

2、隻要這個實體在請求接口的傳回值上（即使是泛型），都能映射到實體項中：

@RequestMapping("/getUser")
public User getUser(){
   return new User();
}
           

3、重新開機檢視測試

注：并不是因為@ApiModel這個注解讓實體顯示在這裡了，而是隻要出現在接口方法的傳回值上的實體都會顯示在這裡，而@ApiModel和@ApiModelProperty這兩個注解隻是為實體添加注釋的。

@ApiModel為類添加注釋

@ApiModelProperty為類屬性添加注釋

常用注解

Swagger的所有注解定義在io.swagger.annotations包下

下面列一些經常用到的，未列舉出來的可以另行查閱說明：

Swagger注解	簡單說明
@Api(tags = “xxx子產品說明”)	作用在子產品類上
@ApiOperation(“xxx接口說明”)	作用在接口方法上
@ApiModel(“xxxPOJO說明”)	作用在模型類上：如VO、BO
@ApiModelProperty(value = “xxx屬性說明”,hidden = true)	作用在類方法和屬性上，hidden設定為true可以隐藏該屬性
@ApiParam(“xxx參數說明”)	作用在參數、方法和字段上，類似@ApiModelProperty

我們也可以給請求的接口配置一些注釋

@ApiOperation("狂神的接口")
@PostMapping("/kuang")
@ResponseBody
public String kuang(@ApiParam("這個名字會被傳回")String username){
   return username;
}
           

這樣的話，可以給一些比較難了解的屬性或者接口，增加一些配置資訊，讓人更容易閱讀！

相較于傳統的Postman或Curl方式測試接口，使用swagger簡直就是傻瓜式操作，不需要額外說明文檔(寫得好本身就是文檔)而且更不容易出錯，隻需要錄入資料然後點選Execute，如果再配合自動化架構，可以說基本就不需要人為操作了。

Swagger是個優秀的工具，現在國内已經有很多的中小型網際網路公司都在使用它，相較于傳統的要先出Word接口文檔再測試的方式，顯然這樣也更符合現在的快速疊代開發行情。當然了，提醒下大家在正式環境要記得關閉Swagger，一來出于安全考慮二來也可以節省運作時記憶體。

拓展：其他皮膚

我們可以導入不同的包實作不同的皮膚定義：

1、預設的 通路 http://localhost:8080/swagger-ui.html

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
           

2、bootstrap-ui 通路 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>
           

3、Layui-ui 通路 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>
           

4、mg-ui 通路 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>