學習目標：

瞭解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>