走进Java接口测试之接口管理工具Swagger2

前言

现在都奉行前后端分离开发和微服务大行其道，前后端技术在各自道路上越走越远。
前后端唯一联系变成了API接口，API文档变成了前后端开发人员&测试人员联系的纽带。所以一款强大的Restful API文档就变得至关重要了。而目前在后端领域，基本上是Swagger的天下了。

Swagger2综述

Swagger是一款Restful 接口的文档在线自动生成、功能测试框架。一个规范和完整的框架，用于生成、描述、调用和可视化Restful 风格的Web服务，加上Swagger-UI，可以有很好的呈现。

Swagger是一组开源项目，其中主要项目如下：

• Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
• Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
• Swagger-js: 用于JavaScript的Swagger实现。
• Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
• Swagger-UI：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
• Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

Swagger-UI 是什么？

Swagger-UI 是一款Restful接口的文档在线自动生成+功能测试功能软件。
Swagger-UI 的官方地址：http://swagger.io/
Github上的项目地址：https://github.com/swagger-api/swagger-ui
官方提供的demo地址：http://petstore.swagger.io/

为什么API接口文档用Swagger-UI ？

现在多数的项目开发中，网站和移动端都需要进行数据交互和对接，这少不了使用Restful编写API接口这种场景。 特别是不同开发&测试团队协作时，就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本，达到事半功倍的效果。
有时对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。即API文档应具备直接执行能力，这种能力类似word,wiki等是无法提供。Swagger-UI 就是这样一种利器，基于Html+Javascript实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。

Swagger-UI 怎么用？

目前官方提供的Swagger-UI 的使用方式主要有2种：

• 与不同的服务端代码集成，在服务端代码中嵌入SwaggerUI文档生成代码，部署时自动生成。
• 手动编辑对应的Json文档，该Json文档有其特定格式，相对比较复杂，手动编写难度比较大，可通过官方提供的在线编辑来实现。

与SpringBoot集成

pom依赖包

  <!--引入swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

编写配置文件SwaggerConfig

/**
 * 主要是添加注解@EnableSwagger2和定义Docket的bean类。
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //是否开启swagger，正式环境一般是需要关闭的，可根据Springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled).select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("com.techstar"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用示例")
                .description("7DGroup | zuozewei")
                // 作者信息
                .contact(new Contact("zuozewei", "https://blog.csdn.net/zuozewei", "zuozewei@hotmail.com"))
                .version("1.0.0")
                .build();
    }
}

添加文档内容(一般上是在Controller，请求参数上进行注解)
添加MyGetMethod类，这里演示两个Get请求

@RestController
@RequestMapping("/")
@Api(tags = "API文档",value = "/",description = "这是我全部的Get方法")
public class MyGetMethod {

    @GetMapping(value = "/getCookies")
    @ApiOperation(value = "通过这个方法可以获取到Cookies",httpMethod = "GET")
    public String getCookies(HttpServletResponse response){
        //HttpServerletRequest 装请求信息的类
        //HttpServerletResponse  装响应信息的类
        Cookie cookie = new Cookie("login","true");
        response.addCookie(cookie);
        return "恭喜zuozewei获得cookies信息成功";
    }

    /**
     * 要求客户端携带cookies访问
     * 这是一个需要携带cookies信息才能访问的get请求
     */
    @GetMapping(value = "/get/with/cookies")
    @ApiOperation(value = "通过这个方法可以获取到Cookies",httpMethod = "GET")
    public String getWithCookies(HttpServletRequest request){
        Cookie[] cookies = request.getCookies();
        if (Objects.isNull(cookies)){
            return "必须携带cookies信息来";
        }
        for (Cookie cookie:cookies){
            if (cookie.getName().equals("login") && cookie.getValue().equals("true")){
                return "这是一个需要带着cookies信息才能访问的get请求";
            }
        }

        return "必须携带cookies信息来";
    }
}

配置全局配置文件application.properties

# 默认的端口号
server.port=8888

# 开启swagger
swagger.enabled=true

启动项目

Swagger-UI 访问与使用

API首页路径：http://127.0.0.1:8888/swagger-ui.html

点击需要访问的API列表，查看接口详情，点击try it out按钮测试
执行测试

服务端返回结果

Swagger使用的注解及其说明：
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• l code：数字，例如400
• l message：信息，例如"请求参数没填好"
• l response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性

对于其他注解，大家可自动谷歌，毕竟常用的就这几个了。有了swagger之后，原本一些接口请求需要Postman这样的调试工具来进行发起，而现在直接在页面上就可以进行调试了，是不是很爽？
对于测试人员，有了这份API文档也是一目了然，不需要和后端多少沟通成本，按着API说明进行接口测试脚本开发即可。

小结

本文主要是对Swagger的简单使用和Springboot集成进行了说明，详细的用法，可自行搜索相关资料下，这里就不阐述了。因为对于百分之八十之上的文档要求基本能满足了。最后，一定要在生产环境关闭Swagger,基于安全因素。

项目源码地址：

• https://github.com/zuozewei/blog-example/tree/master/Java-api-test/06-api-management/springboot-swagger-demo