springboot 集成Swagger2 (二)

上一講初步配置了swagger，這一講對swagger進行詳細的講解

Swagger配置詳解

1、Swagger實例Bean是Docket，所以通過配置Docket實例來配置Swaggger。

@Bean //配置docket以配置Swagger具體參數
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());
}

 

配置掃描接口

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();
}

 

配置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的配置文件查看效果！

 

配置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，一來出於安全考慮二來也可以節省運行時內存。