丝袜哥

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-swagger2springfox-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
Logo

CSDN联合极客时间,共同打造面向开发者的精品内容学习社区,助力成长!

更多推荐