springBoot中集成Swagger

目标：

• 了解Swagger的作用和概念
• 了解前后端分离
• 在springBoot中集成Swagger

Swagger简介

前后端分离

VUE+springBoot

• 后端 ：后端控制层、服务层、数据访问层
• 前端 ：前端控制层、视图层
• 前后端通过API进行交互
• 前后端相对独立，松耦合
• 可以部署在不同的服务器上

产生的问题

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

解决方案

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

Swagger

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

SpringBoot集成Swagger

1. 新建一个springboot-web项目

2. 下载maven依赖https://mvnrepository.com/search?q=springfox

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12

   高版本是没有第5部的测试页面

   3.0.0版本的要先在启动类中加上注解@EnableOpenApi先在导入<groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId>

3. 编写Controller，测试运行成功

4. 配置Swagger=》在包Config下

   package com.hxl.config;
   
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
   
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

5. 测试运行：http://localhost:8080/swagger-ui.html

   

配置Swagger

1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

   //配置了Swagger的Docket实例
   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2);
   }
   1
   2
   3
   4
   5

2. 再通过ApiInfo()属性配置文档信息

   private ApiInfo apiInfo(){
       //作者信息
       Contact contact = new Contact("王木木","https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343","11@qq.com");
       return new ApiInfo(
           "Swagger笔记", //标题
           "冲冲冲", //描述
           "v1.0。0", //版本
           "https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343", //组织链接
           contact, //联系人信息
           "Apach 2.0 许可", //许可
           "许可链接", //许可连接
           new ArrayList<>()//扩展
       );
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14

3. Docket关联上ApiInfo

   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
   }
   1
   2
   3
   4

4. 启动项目，访问http://localhost:8080/swagger-ui.html

   

Swagger配置扫描接口

构建Docket时通过select()方法配置怎么扫描接口。select()和build()是一套的

//配置了Swagger的Docket实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        /*
                RequestHandlerSelectors：要扫描接口的方式
                basePackage：指定要扫描的包
                any()：扫描全部
                none()：不扫描
                withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                withMethodAnnotation：扫描方法上的注解
                path()：过滤什么路径
                */
        .apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))
        //.paths(PathSelectors.ant("/hxl/**"))
        .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

我们看之前的运行结构可以看到有base-error-controller和hello-controller，一旦使用了上述配置后，运行结果只有hello-controller

配置是否启动Swagger

通过enable()方法配置是否启用swagger

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //enable是否启动Swagger，默认为true，如果该位false则不能在浏览器中访问
        .enable(false)
        .select()
        /*
                RequestHandlerSelectors：要扫描接口的方式
                basePackage：指定要扫描的包
                any()：扫描全部
                none()：不扫描
                withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                withMethodAnnotation：扫描方法上的注解
                path()：过滤什么路径
                */
        .apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))
        //.paths(PathSelectors.ant("/hxl/**"))
        .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Swagger在生产环境中使用，在发布的时候不使用

• 判断是否是生产环境
• 注入enable()值

当我们有多个生产环境时。比如说application-dev.yaml和application-pro.yaml。动态设置当前项目处于dev时显示swagger，Pro是不显示

#哪个环境生效
spring.profiles.active=dev
1
2

设置我们的dev走8081，默认走8080，pro走8082

然后修改我们的配置

@Bean
public Docket docket(Environment environment){

    //设置显示的Swagger环境
    Profiles profiles = Profiles.of("dev", "test");
    //通过  判断是否处在自己设定的环境中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //这里变成了flag
        .enable(flag)
        .select()     
        .apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))
        .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

此时我们就发现，如果我们走默认的8080是没有Swagger的，走8081才有

配置API文档的分组

@Bean
public Docket docket(Environment environment){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("王木木");
    //其余配置省略
}
1
2
3
4
5
6
7

启动项目就发现我们的组别有了

如果有多个分组怎么办？只需要配置多个docket即可

//其他的环境需要自己填
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("天");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("狼");
}
1
2
3
4
5
6
7
8
9

实体类配置

1. 创建一个实体类

   package com.hxl.pojo;
   
   public class User {
       public String username;
       public String password;
   }
   1
   2
   3
   4
   5
   6

2. 只要这个实体在请求接口的返回值上，就可以映射到实体项中

   //只要我们的接口中，返回值存在实体类，他就会扫描到Swagger中
   @PostMapping("/user")
   public User user(){
       return new User();
   }
   1
   2
   3
   4
   5

3. 测试

   

4. 此时发现我们的Model中有了User。如果有中文的注释，只需要在加两个注解

   package com.hxl.pojo;
   
   import io.swagger.annotations.ApiModel;
   import io.swagger.annotations.ApiModelProperty;
   
   //@Api("注释")
   @ApiModel("用户实体类")
   public class User {
       @ApiModelProperty("姓名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13

5. 测试

   

常用的注解

Swagger的所有注解定义在io.swagger.annotations包下

注解在类上的可以看一下上面的，接下来看注解在接口方法上，以及参数上

@ApiOperation("王木木的接口")
@PostMapping("/hxl")
public String hxl(@ApiParam("用户名")String username){
    return username;
}
1
2
3
4
5

在这里还可以进行测试

小结

1. 我们可以通过Swagger给一些比较难理解的属性或者接口增加注释信息
2. 接口文档实时更新
3. 可以在线测试
4. 在正式发布的时候一定要关闭Swagger《安全；节省运行的内存》