【SpringBoot】18、整合Swagger 3.0【狂神篇】

丝袜哥

1、Swagger简介

• Restful Api 文档在线自动生成器

  API 文档 与API 定义同步更新

  不再需要手工写API文档

• 直接运行，在线测试API

2、集成Swagger

SpringBoot 集成 Swagger 3.0.0

与 Swagger2.x.x 是有区别的

1）新建web项目

2）pom.xml 引入启动器

Swagger 3.0.0 只需要引入启动器 springfox-boot-starter

Swagger 2.x.x 需要引入两个jar包 springfox-swagger2 和springfox-swagger-ui

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3）配置类SwaggerConfig

@EnableWebMvc 也可以加在入口程序上

Swagger2.x.x 中使用 @EnableSwagger2

@Configuration
@EnableWebMvc
public class SwaggerConfig {

}

4）测试

Swagger 3.0 访问地址：http://.../swagger-ui/index.html

2.x.x 中是：http://.../swagger-ui.html

3、配置Swagger

Swagger实例Bean是Docket，通过配置Docket实例来配置Swaggger

在 SwaggerConfig 中添加

/**
* 配置Swagger具体参数
* @return
*/
@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo());
}

/**
* 自定义API文档信息
* @return
*/
private ApiInfo apiInfo(){
    // 作者信息
    Contact contact = new Contact("土味儿", "http://localhost:8080/", "2141421414@qq.com");

    return new ApiInfo(
        "Hello Swagger API 文档",
        "大道无垠 行者无疆",
        "v1.0",
        "http://localhost:8080/",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList());
}

4、配置扫描接口

@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
        .select()
        // 只扫描特定包下的接口
        .apis(RequestHandlerSelectors.basePackage("com.tuwer.controller"))
        .build();
}

• 扫描方式

  .select().apis(RequestHandlerSelectors.xxx).build()

@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
        .select()
        // 只扫描特定包下的接口
        //.apis(RequestHandlerSelectors.basePackage("com.tuwer.controller"))
        //.apis(RequestHandlerSelectors.any())
        //.apis(RequestHandlerSelectors.none())
        //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
        .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
        .build();
}

• 配置接口扫描过滤

  .paths(PathSelectors.ant("/hello/**"))

@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
        .select()
        // 只扫描特定包下的接口
        //.apis(RequestHandlerSelectors.basePackage("com.tuwer.controller"))
        //.apis(RequestHandlerSelectors.any())
        //.apis(RequestHandlerSelectors.none())
        //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
        .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
        // 只扫描请求以/hello开头的接口
        .paths(PathSelectors.ant("/hello/**"))
        .build();
}

5、配置Swagger开关

enable(boolean externallyConfiguredFlag)

是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
        //.apiInfo(apiInfo())
        .enable(true)
        // ...
        .build();
}

• 根据项目环境决定是否启用Swagger

如：开发dev、测试test 环境下启用，生产production 环境下不启用

多环境 application.yml

# 选择要激活的环境
spring:
  profiles:
    active: prod

---
# 生产环境
server:
  port: 8080
spring:
  config:
    active:
      on-profile: prod

---
# 开发环境
server:
  port: 8081
spring:
  config:
    activate:
      on-profile: dev

---
# 测试环境
server:
  port: 8082
spring:
  config:
    activate:
      on-profile: test

自动判断是否启用Swagger

@Bean
public Docket docket(Environment environment){
    // 允许启用Swagger的环境
    Profiles profile = Profiles.of("dev","test");
    // 判断当前环境与指定环境是否一致
    boolean b = environment.acceptsProfiles(profile);

    return new Docket(DocumentationType.OAS_30)
        .apiInfo(apiInfo())
        // 根据当前环境判断是否启用Swagger
        .enable(b)
        // ...
        .build();
}

6、配置API分组

groupName()

默认为 default

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

• 配置方法分组

  只需要定义多个 Docket docket() 方法

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

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

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

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.OAS_30).groupName("D");
}

7、实体配置

1）新建实体

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户类",description = "用户实体")
public class User {
    @ApiModelProperty(value = "用户名",example = "如：张三")
    private String name;
    @ApiModelProperty(value = "用户密码;字母、数字、下划线，至少6位")
    private String ps;
}

导入 lombok

2）Controller

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

3）测试

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而 @ApiModel 和 @ApiModelProperty 这两个注解只是为实体添加注释的。

@ApiModel 为类添加注释

@ApiModelProperty 为类属性添加注释

8、常用注解

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty