Swagger 的介紹以及使用

本文代碼已經同步到碼云 ，歡迎大家 star https://gitee.com/njitzyd/JavaDemoCollection

Swagger 簡介

Swagger 是一個主要用來在線生成文檔的插件，這里主要用來動態生成api接口供前后端進行交互，如果不生成的話就需要寫靜態文檔來交互，那樣不僅很慢而且不容易修改，那Swagger就可以解決這個問題。

• 號稱世界上最流行的API框架
• Restful Api 文檔在線自動生成器 => API 文檔 與API 定義同步更新
• 直接運行，在線測試API
• 支持多種語言 （如：Java，PHP等）
• 官網：https://swagger.io/

swagger 的使用（基于SpringBoot）

1.引入依賴

新建一個SpringBoot 項目，只加入 web 的啟動器，然后添加下面兩個依賴：

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

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

2.創建一個DemoController

@RestController
public class DemoController {

    /**
     *
     * @description: 注意這種寫法Swagger 會生成很多個接口（雖然參數里指定了GET，Swagger掃描不到）
     * 所以在實際的開發中盡量使用 @GetMapping 等這種指定了方法的方式
     * @param: []
     * @return: java.lang.String
     * @date: 2020/8/2 
     */
    @RequestMapping(value = "index",method = RequestMethod.GET)
    public String hello(){
        return "helloWorld";
    }
}

3.創建Swagger 的配置類

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

4.啟動項目

訪問地址：http://localhost:8080/swagger-ui.html，可以看到Swagger 的頁面：

image-20200802175756924

Swagger 的配置

剛剛啟動后，頁面的內容都是默認的，在實際使用中需要我們進行配置。

配置Swagger 掃描的接口

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

其中RequestHandlerSelectors 有很多可以配置的方法,具體如下，可以根據自己的項目選擇：

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) // 根據包路徑掃描接口

除此之外，我們還可以通過.paths配置接口掃描過濾：

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

PathSelectors 也是可以多種配置的：

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

配置Swagger 的開關

通過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.njit.swagger.controller"))
       // 配置如何通過path過濾,即這里只掃描請求以/njit開頭的接口
      .paths(PathSelectors.ant("/njit/**"))
      .build();
}

動態配置當項目處于test、dev環境時顯示swagger，否則不顯示

首先在application.properties 中配置激活的配合環境，然后再做如下配置：

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

配置API分組

很簡單只要配置groupName()即可，如果想要配置多個分組，name就配多個Docket實例，注意實例的名稱不能重復。

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

配置多個分組

@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");
}

實體配置

1. 新建一個實體類可以在上面使用注解（注意，如果接口中的返回值中有實體類，name實體類就會自動被識別為model，無論你加不加注解，當然加注解后會顯示你加的注解，比較詳細）

// @ApiModel為類添加注釋
// @ApiModelProperty為類屬性添加注釋
@ApiModel("用戶實體")
public class User {
   @ApiModelProperty("用戶名")
   public String username;
   @ApiModelProperty("密碼")
   public String password;
}

常用注解

這樣就可以在controller類以及方法以及參數中使用相應的注解來完善我們的Swagger，特別說明的是，在生產環境中一定要關閉Swagger，一方面提高性能，更重要的是安全問題，會把自己的接口暴露出去！！！