Swagger_测试工具_2小时精通

什么是前后端分离

后端时代：

​ 前端只需要管理静态页面，大部分项目还是交由后端完成，以前的JavaWeb项目大多数都是java程序使用模板引擎，又当爹又当妈，又搞前端（ajax/jquery/js/html/css等等），又搞后端（java/mysql/oracle等等）。

前后端分离：

​ 核心思想是前端html页面通过ajax调用后端的restuful api接口并使用json数据进行交互。

• 后端：后端控制层，服务层，数据访问层
• 前端：前端控制层，视图层
  • 前端在运行时，使用伪造数据（JSON格式）可以直接独立运行无需后端，项目也能跑起来。

产生的问题：

​ 前后端集成联调，前端人员和后端人员无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案：

​ 首先指点 schema[计划的提纲]，实时更新最新API，降低集成的风险

• 以前：制定 word 计划文档
• 现在
  • 前端测试后端接口：postman（一款测试接口的软件）
  • 后端提供接口，需要实时更新最新的消息及改动

Swagger 简介

• 号称世界上最流行的 API框架

• RestFul API 文档在线自动生成工具

• 直接运行，可以在线测试 API接口

• 多语言的支持

Swagger 整合 Spring Boot

• 创建一个SpringBoot 的web项目
• 导入相关依赖

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

• 编写一个Hello 工程

• 配置swagger

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

• test

使用 http://localhost:8080/swagger-ui.html 访问就可以进入swagger index界面

配置 Swagger

• Swagger的bean实例 Docket

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置了Swagger的Docket的bean实例
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger 信息apiinfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact concat = new Contact("Kanan", "https://blog.csdn.net/weixin_43206491", "z-houjie@qq.com");
        return new ApiInfo(
                "Kanna的SwaggerAPI文档",
                "青山不改绿色长流,你我山巅自相逢",
                "v1.0",
                "https://blog.csdn.net/weixin_43206491",
                concat,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

• 配置扫描接口

/**
     * 配置了Swagger的Docket的bean实例
     * @return
     */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描的接口方式
        //basePackage() 指定要扫描的包
        //any() 扫描全部
        //none() 不扫描
        //withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
        //withMethodAnnotation 扫描方法上的注解
        .apis(RequestHandlerSelectors.basePackage("com.kanan.controller"))
        //过滤什么路径
        //.paths(PathSelectors.ant("/kanan/**")) //只扫描/kanan路径下的请求
        .build();
}

• 配置是否启动

  //是否启用swagger默认启动
  .enable(false) //关闭
  

开发场景

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

• 判断是否是生产环境 flag = false
• 注入enable(false)

具体实现：

• 首先创建两套配置文件（一个生产环境，一个发布环境）

application-dev.yml
application-pro.yml

• 在application.yml 中设置使用的环境

spring:
  profiles:
    active: dev #设置生产环境为 dev

• 配置swagger配置类

@Bean
    public Docket docket(Environment environment){

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

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag) //是否启用swagger默认启动
                .select()
                //RequestHandlerSelectors 配置要扫描的接口方式
                //basePackage() 指定要扫描的包
                //any() 扫描全部
                //none() 不扫描
                //withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.kanan.controller"))
                //过滤什么路径
                //.paths(PathSelectors.ant("/kanan/**")) //只扫描/kanan路径下的请求
                .build();
    }

配置API文档的分组

.groupName("Kanan")

在Spring中注册多个 Docket 对象即为多个分组,例：

@Bean
public Docket wananDocket(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("Wanan");
}

@Bean
public Docket jananDocket(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("Janan");
}

对于在协作开发中，自己配置自己的 Docket 就可以选择多个组，这个在协作开发中非常方便

Models 文档展示

//只要接口的返回值中存在某个实体类，它就会被扫描到swagger中
@PostMapping("/user")
public User getUser(){
    return new User();
}

• 添加文档说明

@ApiModel("用户实体类")
@Data
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

@Api(value="通过用户的登陆注册等接口",tags="用户管理")
public class UserController{
}

@ApiOperation("用户登录")
public void login(){
}

更多文档说明注解（如：接口说明等等）可以查找官方文档

• test

//只要接口的返回值中存在某个实体类，它就会被扫描到swagger中
@PostMapping("/user")
public User addUser(User param){
    User user = null;
    if (param != null){
        user = new User();
        user.setUsername(param.getUsername());
        user.setPassword(param.getPassword());
    }
    return user;
}