Swagger2-前后端分离利器

让前端知道你的改变–swagger

项目仓库：https://gitee.com/chzsw/introduction-to-swagger

swagger的作用：

swagger的作用有：解释接口、与在线测试。
解释接口让前端知道接口的功能、传入值的要求、返回的值。
而在线测试可以测试接口是否能用

带着问题去学习：

swagger页面：

1、如何配置swagger的基本信息
2、如何自定义扫描的接口（有几种方式，分别是什么）
3、如何过滤自定义的接口
4、如果关闭swagger,并根据环境设置是否启动
5、如果分组，如一个 控制器内容为一组
6，如何描述方法功能，传入参数与返回参数

swagger的配置:

这是说明与spring boot的集成、配置基本信息、配置扫描接口与使用过滤器 的配置过程

spring boot 的集成

准备一个简单的spring boot项目，添加一个控制器。如http://localhost:8080/hello

1. 添加依赖

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

2. 创建一个配置类

@Configuration
@EnableSwagger2    //开启swagger
public class SwaggerConfig {
}

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

配置基本信息

就是修改hmtl中swagger信息部分如标题、描述，只需要修改配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean //配置docket以配置swagger具体参数
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

重启就可以看见效果了，这里我们用自定义的apilnfo覆盖了默认的

配置扫描接口

html中有接口信息，这里可以设置显示那些接口信息。
.apis(RequestHandlerSelectors.withMethodAnnotation(PostMapping.class)) 如果使用@PostMapping注解，会被扫描到，而@GetMapping不会

 @Bean //配置docket以配置swagger具体参数
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() //开始设置，会返回一个ApiSelectorBuilder对象
                .apis(RequestHandlerSelectors.none()) //none代表都不扫描，此时重启浏览会发现不显示接口信息
                .build(); //结束设置，会把ApiSelectorBuilder构建为Docket
    }

 			.apis(RequestHandlerSelectors.none())  //none 全不扫描
            .apis(RequestHandlerSelectors.any())   //any 扫描所有 
            .apis(RequestHandlerSelectors.basePackage("com.example.cainiao.Controller")) //扫描特定的包
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) //如果类上有特定的注解扫描
            .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)) //如果方法上有特定的注解扫描

过滤扫描

相当于在apis在进行一次过滤，如果ant可以对具体的请求过滤

@Bean //配置docket以配置swagger具体参数
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())   //any 扫描所有
                .paths(PathSelectors.ant("/h/**")) //这里只扫描以/h开头的注解，相当于对apis的过滤
                .build();
    }

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

swagger的使用

介绍swagger的注解使用，包含分组的配置、方法的介绍、解释返回对象、传入参数的解释
swagger是用来告诉前端，后端做了什么，对前端来说方法的功能，如何传入参数，拿到参数的意义是最重要的。

分组

如果一个项目有多个控制器，把所有的文档在一个页面显示，这不利于操作。分组可以看成分页，如一个页面只显示一个控制器的功能。
如下，只需要定义n个返回docket的bean就可以了，通过groupName()对分页设置名。
每个具体的docket就可以通过apis指定要扫描的接口了

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //创建多个分组
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("controller1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("controller2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("controller1");
    }

通过切换控制器，查看对应的内容

方法功能介绍

@ApiOperation注解可以对方法进行描述，让前端知道这个方法的具体功能

 @ApiOperation("/hello2方法，这个方法可以返回 ss")
    @GetMapping("/hello2")
    public String hello2(User user){
        return "ss";
    }

传入参数解释

如果是一个普通参数：
在参数前使用@ApiParam就可以了
@GetMapping("/hello")
public String hello(@ApiParam(“用户名:”)String username){
return “hello”;
}

如果是一个对象：
只需要进入这个对象，给每个参数添加注解就可以了@ApiModel 描述对象,@ApiModelProperty 描述参数

 @GetMapping("/hello")
    public String hello(User username){
        return "hello";
    }

在线测试

可以网页上对这个接口进行测试，不需要在打开专门的测试软件（如postman)

swagger案例

如何在运行环境下关闭swagger

swagger运行是消耗内存的，可以设置在运行时关闭

@Bean //配置docket以配置swagger具体参数
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)  //enable可以设置swagger是否启动，为true时启动
                .build();
    }

运行时只有获取运行时的环境，就可以通过enable()判断是否启动swagger。
先准备生产环境与运行环境

@Bean //配置docket以配置swagger具体参数
    public Docket docket(Environment environment){
        //设置要显示swagger的环境
        Profiles of = Profiles.of("dev");
        //判断当前是处于该环境
        boolean b = environment.acceptsProfiles(of);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)
                .build();
    }

可见如果当前环境为dev ,environment.acceptsProfiles(of);会返回true，此时swagger就打开了。