Swagger简介

前后端分离

  • 前端 -> 前端控制层、视图层
  • 后端 -> 后端控制层、服务层、数据访问层
  • 前后端通过API进行交互
  • 前后端相对独立且松耦合

产生的问题

  • 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

  • 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

Swagger

  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行，在线测试API
  • 支持多种语言 （如：Java，PHP等）
  • 官网：https://swagger.io/

这玩意就是方便你测试接口用的，postman太麻烦了

spring boot 集成swagger

SpringBoot集成Swagger => springfox，两个jar包

  • springfox ui
  • springfox swagger2

使用swagger

  1. 新建一个springboot = web项目

  2. 导入相关依赖

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    <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>

    <!--3.0版本-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

  3. 编写一个hello工程

  4. 配置swagger==>config

    1
    2
    3
    4
    5
    6
    7
    8
    9
    //用@Configuration注释类表明其主要目的是作为bean定义的源
    //表明它是一个配置类
    @Configuration
    //@EnableSwagger2 //开启swagger
    @EnableOpenApi //3.0版本开启方式
    public class SwaggerConfig {


    }

  5. 测试运行

    访问地址 (http://localhost:8080/swagger-ui/index.html)

image-20211208225118754

配置swagger页面信息

swagger的bean实例Docket 自定义信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//配置swagger的Docket的bean的实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo());
}
//配置swaggerApi信息
private ApiInfo apiInfo(){
    //配置维护人信息
    //姓名，url ，邮箱
    Contact contact = new Contact("yang","https://github.com","914405257@qq.com");
    return new ApiInfo(
        "Yang的Swagger文档",   //标题
        "这个作者有点酷", //描述
        "3.0", //版本
        "https://github.com",  //服务条款URL
        contact, //维护人信息
        "Apache", //许可证
        "http://www.apache.org/licenses/LICENSE-2.0", //许可证URL
        new ArrayList<>() //供应商信息
    );
}

image-20211208233816376

swagger配置扫描接口

Docket.select

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        // basePackage 扫描指定包中的swagger注解
        //any 扫描全部
        //none: 都不扫描
        //withClassAnnotation 扫描类上的注解 参数是一个注解的反射对象
        //withMethodAnnotation 扫描方法上的注解
        //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
        //.apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)
        .apis(RequestHandlerSelectors.basePackage("com.yang.swagger.controller"))
        //过滤什么路径 就是指定允许访问的路径
        .paths(PathSelectors.ant("/yang/**"))
        .build();
}

配置是否启动swagger

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//配置swagger的Docket的bean的实例
//配置是否启用swagger 如果为FALSE，则swagger不能在浏览器访问
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //配置是否启用swagger
        .enable(false)
        //以下是 select才有的方法
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.yang.swagger.controller"))
        //.paths(PathSelectors.ant("/yang/**"))
        .build();
}

思考

如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@Bean
public Docket docket(Environment environment){
    //设置要显示的swagger环境
    Profiles profiles = Profiles.of("dev");
    // 判断当前是否处于该环境
    // 通过 enable() 接收此参数判断是否要显示
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(flag)//配置是否启用swagger 如果为FALSE，则swagger不能在浏览器访问
        //以下是 select才有的方法
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.yang.swagger.controller"))
        //.paths(PathSelectors.ant("/yang/**"))
        .build();
}

application.properties

1
spring.profiles.active=dev

application-dev.properties

1
server.port=8081

application-pro.properties

1
server.port=8082

配置API文档分组

1
.groupName("洋") //配置分组

如何配置多个分组：多个DocKet实例即可

1
2
3
4
5
6
7
8
9
10
11
12
@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");
}

image-20220408224651646

swagger注解的使用

1
2
3
4
5
6
7
8
9
10
11
@Api： 用于类，标识这个类是swagger的资源
@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描
@ApiOperation： 用于方法，描述 Controller类中的 method接口
@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收
@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiImplicitParam： 用于方法，表示单独的请求参数
@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam
@ApiResponse： 用于方法，描述单个出参信息
@ApiResponses： 用于方法，包含多个@ApiResponse
@ApiError： 用于方法，接口错误所返回的信息

实体类

1
2
3
4
5
6
7
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

controller

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
@Api(tags = "hello控制类")//对请求类的说明
@RestController
public class HelloController {
    @ApiOperation("hello请求")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的接口中，返回值中存在实体类，他就会被扫描到swagger中
    @ApiOperation("user请求") //方法的说明
    @PostMapping("/user")
    public User user(){
        return new User();
    }

    @ApiOperation("hello2请求")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String userName){
        return "hello"+userName;
    }


    //使用对象接收数据 这个对象由springmvc通过反射创建 使用set方法写入数据，这里没有set方法 所以是null
    @ApiOperation("Post请求")
    @GetMapping("/postT")
    public User postT(User user){
        return user;
    }

}