基于swagger2和Postman的接口测试实践（自动生成接口文档和测试用例）

端午安康！下午家庭聚会到很晚，宝子睡了终于可以补个之前调研的作业了。

今天来聊聊我觉得非常好且易于落地的一种接口测试方案，对于没有代码经验的测试团队也可以实施，当然有的话就会事半功倍了。

• 为什么要做接口测试

  

测试金字塔，我想大家已经很了解了，从下到上，自动化难度越来越大，收益却越来越小。对于测试团队，做单元测试不太现实，做界面测试的难度和花费又很高，所以从接口层开始做较高覆盖的自动化测试无疑是性价比最高的了。还有就是目前的软件系统大多是前后端分离以及前端框架的成熟度和稳定性越来越高，这些都为接口测试创造了有利条件，我们从接口可以验证绝大多数系统的功能逻辑。

• 为什么很多项目中不做接口测试

  很多项目迭代速度很快，测试却还都是手工，问测试为什么不做自动化啊，回答较多的是不会做界面自动化。确实，让所有测试都会做界面自动化是不可能的，有那能力为什么不去做开发？那为什么不做接口自动化那？主要原因有二：

1. 压根没有接口文档！——文档理论上属于产品的产出，而产品人员不一定有编程基础，所以无法写接口文档。让开发写接口文档？我只能说能认真写接口文档的开发都是好开发！

2. 测试不会做接口测试——确实，接口测试都是测的协议，想测明白了就得学习一些基础的协议知识，如HTTP、Restful这些。其次，再学习下通用的接口测试工具，如soapUI、postman。其实这些也还好学，简单的培训培训都可以上手，但是上手之后按接口文档创建出具体的用例脚本也是需要一定难度和积累的。

• Swagger和Postman组合拳

 解决了上面提到的问题，我想接口测试就没什么实施不下去的了吧。

1. Swagger能做什么

   Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

   https://www.oschina.net/p/swagger?hmsr=aladdin1e1

   我翻译一下重点：swagger可以用来编写接口文档或者生成接口文档、自动创建出接口文档的网站、根据接口文档自动生成服务端和客户端的代码（厉害吧，支持Java、Python、JS、Go、PHP等主流语言）。

   Swagger官网：swagger.io& Design Tools for Teams | Swagger

   

   

   ​




2. Swagger怎么用

   因为目前后端主流是使用java-springboot开发为主，以下以springboot为例介绍

1. 方式A：在SpringBoot中以注解方式插入注释来生成swagger文档

1. 引入Dependence

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

2. 创建配置类

   package com.learn.boot.helloworld.config;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.context.annotation.Profile;
   import org.springframework.web.servlet.config.annotation.EnableWebMvc;
   
   
   
   
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.ApiInfo;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   
   @Configuration //声明该类为配置类
   @EnableSwagger2 //声明启动Swagger2
   @Profile({"dev","test"})
   public class SwaggerConfig{
       @Bean
       public Docket customDocket() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.learn.boot.helloworld.controller"))//扫描的包路径
                   .build();
       }
   
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("Swagger文档")//文档说明
                   .version("1.0.0")//文档版本说明
                   .build();
       }
   }
   

3. 加入API注解

    API注解可以在controller里加，也可以在Bean里，看具体需要

   常用注解为：

   @Api
   @ApiOperation
   @ApiModel
   @ApiModelProperty
   @ApiParam
   @ApiResponse
   @ApiResponses
   @ResponseHeader

   

   
   

   

4. 启动程序

在application.properties中设置好端口号，启动程序后在浏览器中输入url：http://localhost:8081/swagger-ui.html#







可以通过springboot配置中的环境标识和swaggerconfig类中的配置来选择在哪个环境启用swagger

spring.profiles.active=test



生成的文档如下：




2. 方式B：通过Swagger Editor编写文档生成server端、client端代码

1. Node安装Swagger Editor

   安装httpserver：npm install -g http-server

   克隆代码：git clone https://github.com/swagger-api/swagger-editor

   启动：http-server swagger-editor

   如果成功了，如下可以看到已经有的接口示例

   

2. 按需修改文档后，生成代码并引入到项目中

   

   
   

3. Postman的引入

1. 直接在Postman中导入

   上边两种方式生成的swagger文档都可以导出json文件。

   
   

   
   

   

   之后打开Postman并import

   

   
   

2. 通过官方提供的代码导入

   npm安装：npm i swagger2-to-postman

   在test/converter-spec.js中修改参数，并执行命令

   $ npx mocha test/*-spec.js;

   

   复制出json并保存到xx.collection.json即可。

   注意：代码生成的postman测试脚本的版本是1.0，若需要改成目前使用的2.0版本需要安装postman转换器

   npm install -g postman-collection-transformer

   转换命令：postman-collection-transformer convert -i “转换文件路径” -o “转换后文件路径” -j 1.0.0 -p 2.0.0 -P
   

• More

1. 关于swagger的应用，无论哪种方式，测试不必太深入到具体实施方法中，只需在开发团队中推进并保证输出的接口文档规范即可。个人更推荐方式B，因为B不仅生成的Postman脚本更好，而且也会减少很多开发的工作量。

2. 无论怎么样，最终生成的Postman脚本是较基础的脚本，只是根据API和API方法及Response方式来生成的请求，如果需要额外的测试用例我们可以通过coding的方式直接对Postman脚本进行个性化批量修改，或者如果有JavaScript资源的可以基于swagger2-to-postman进行二次开发。
   

3. 类似Swagger，还有rocket-API，简单看了下貌似更加简单高效，以后再研究。