SpringBoot 学习（七）Swagger

7. Swagger

7.1 简介

• 便于前后端集成联调
• RestFul Api 文档在线生成工具 ==> Api 文档与 Api 定义同步更新
• 直接运行，在线测试 Api 接口

7.2 springboot 集成 swagger

(1) 导入依赖

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>
1
2
3
4
5
6
7
8
9
10
11
12

(2) 集成 swagger

@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {
}
1
2
3
4

(3) swagger 页面信息

接口：localhost://8080/swagger-ui.html

(4) 配置 swagger 信息

@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {

    // 配置 Swagger Docket 的 bean 实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    // 配置 swagger api 信息
    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("why", "https://gitee.com/", "1942953841@qq.com");
        return new ApiInfo("Why Swagger Api Info",
                            "Why so serious!!!",
                            "v1.0",
                            "https://gitee.com/",
                            contact,
                            "Apache 2.0",
                            "http://www.apache.org/licenses/LICENSE-2.0",
                            new ArrayList()
        );
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

(5) 配置 swagger 自定义扫描接口

// 多环境配置，注解方法
@PropertySource(value = "classpath:application.properties")
@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {

    // 配置 Swagger Docket 的 bean 实例
    @Bean
    public Docket docket(Environment environment) {
        // 多环境配置，java 方法
        // 设置要显示的 swagger 环境
        // Profiles profiles = Profiles.of("dev", "test");
        // 判断是否处在自己设定的环境中
        // boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // enable 是否启用 swagger
                // .enable(flag)
                .select()
                // RequestHandlerSelectors 配置扫描接口的方式
                // basePackage 指定要扫描的包
                // any() 扫描全部
                // none() 不扫描
                // withClassAnnotation 扫描类上的注解，参数是一个类上的反射对象
                // withMethodAnnotation 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.why.swagger.controller"))
                // paths 路径过滤
                // .paths(PathSelectors.ant("/why/**"))
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

(6) 多文档分组配置

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

(7) 注解的使用

• 实体类

  /**
   * @ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。
   */
  @ApiModel(value = "com.why.pojo.User", description = "用户类")
  @Data
  @AllArgsConstructor
  @NoArgsConstructor
  public class User {
  
      /**
       * @ApiModelProperty() 用于字段，表示对 model 属性的说明。
       */
      @ApiModelProperty("用户名")
      private String username;
  
      @ApiModelProperty("密码")
      private String password;
  }
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18

• 接口

  /**
   * @Api 用在类上，说明该类的作用。
   * tags：接口说明，可以在页面中显示。
   */
  @Api(tags = "Hello 控制器类")
  @RestController
  public class HelloController {
  
      @ApiOperation("hello 方法")
      @GetMapping("/hello")
      public String hello() {
          return "hello";
      }
  
      /**
       * @ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。
       * value：接口名称
       * notes：详细说明
       */
      @ApiOperation(value = "user 控制器", notes = "获取用户")
  
      /**
       * @ApiImplicitParams / @ApiImplicitParam 为单独的请求参数进行说明
       * name：参数名，对应方法中单独的参数名称。
       * value：参数中文说明。
       * required：是否必填。
       * paramType：参数类型，取值为 path、query、body、header、form。
       * dataType：参数数据类型。
       * defaultValue：默认值。
       */
      @ApiImplicitParams({
              @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query", required = true, defaultValue = "why"),
              @ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query", required = true, defaultValue = "123")
      })
  
      /**
       * @ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。
       */
      @ApiResponses({ @ApiResponse(code = 200, message = "OK", response = User.class) })
      
      @PostMapping(value = "/userObj")
      
      /**
       * @ApiParam 用于 Controller 中方法的参数说明。
       * value：参数说明
       * required：是否必填
       */
      public User userObj(@ApiParam(value = "用户名", required = true) String username,
                          @ApiParam(value = "密码", required = true) String password) {
          User user = new User(username, password);
          System.out.println(user);
          return user;
      }
  
  }
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55

(8) 接口测试

• swagger2 测试 get 接口不能传递参数，测试 post 接口可以传递参数

  即含参接口使用 @PostMapping 和 @RequestMapping

• swagger2 测试含参 @GetMapping 会报如下错误：

  TypeError: Failed to execute ‘fetch‘ on ‘Window‘: Request with GET/HEAD method cannot have body.

• 效果

  

  • Get 方法

    

    

    

  • Post

    

    

(9) 安全考虑

• 正式发布一定要关闭 swagger，