敦煌网技术产品团队 Yuhui | 作者

引言：
本文是一篇讲述我司云原生微服务与服务接口 (API) 自动化测试实现的文章;
前半部分主要简单介绍 Swagger 的基本使用方法，中后部分也就是本文的重点议题：Swagger 如何与自动化测试之道结合应用，最后根据整体的实现情况,提出一些注意事项,也就算是欲加理想实现,自要约束规范;
云原生微服务框架项目升级在如火如荼的进行中,根据磐石框架延伸产生的测试技术,亦是本文主旨所在,接下来由非专业的我越俎代庖介绍一二

一、Swagger 介绍

原始时代,可能在工程开发前夕,会去创建接口文档,或者去修改前辈的接口文档.日复一日的你,肯定会有遗漏,那就是忘记维护接口文档 (PS:忘记写文档就扣工资?)

近现代,你可以用 Swagger 自动帮你生成接口文档 (是不是很神奇?) 这就是技术的进步! 但是! 你必须要遵守他的规范 (一提规范就头大)

1.1 Swagger 优缺点:

• 优点:
  自动生成接口文档,只要在代码中使用注解进行标注,就能生成对应的接口文档
  接口文档动态更新 (如果你也更新了注解的话),这样就不会出现忘记更新接口文档的情况
  支持在线调试,让联调测试 So eazy!!! Swagger 提供了在线调用接口的功能,研发代码注解好接口、功能和参数,测试一目了然

• 缺点:
  增加研发代码成本,写一套接口还得再写一套参数配置 (写文档不也是嘛,只是形式不一致而已)
  要遵循规范执行,再好的功能,若没有规范来推动,亦执行不落地 (没错! 又是规范)
  旧版接口文档不会存留 (貌似大家不关心旧版的接口信息),但是终归不会存留
  不能创建测试用例 * 3 (粉笔画重点!!! 重要事情说三遍)

1.2 Swagger 使用:

Swagger 大法图

1. 添加依赖包:(请自行查阅)

2. 定义接口组:

由于业务多样,接口自然也要分组,同业务基本都是在一个 Controller 中的,不同的业务应该定义/划分不同的接口组,接口组可以使用@Api来划分

@Api(tags=”分组”) // tags参数:可以当做是分组的组索引
@RestController
public class SampleController{}

3. 定义接口:

使用@Api来标注一个 Controller 之后,如果下面有接口,就会默认生成文档,但是我们自定义的说明

@Api(tages=”分组”)
@RestController
public class SampleController {
    // @RequestMapping支持7中请求方式,如果method参数未定义值或者定义多个
    // Swagger会解析出很多同接口不同请求的用例(method强烈建议指定一个即可)
    @GetMapping(“/test”)
    public String test(String id) {
        return “Hello World”;
    }
}

来来来,小伙子们,我们继续细化,我们还可以使用@ApiOperation来描述你的接口

@ApiOperation(value=”测试样例”,note=”测试样例备注”)
@GetMapping(“/test”)
public String test(String id) {
    return “Hello World”;
}

上面使用@ApiOperation注解描述接口，这只是一个简单的介绍,具体使用方法以及描述接口注解的参数都有什么, 在此不再多说,感兴趣的读者可以自行搜索

PS:注意一下，对于 GET 方式，swagger 不推荐使用 body 方式来传递数据，不建议在 GET 方式时使用 json、form-data 等方式来传递，最好使用路径参数或者 url 参数。所以如果接口传递的数据是 json 或者 form-data 方式的，建议使用 POST 方式

4. 定义接口响应:(具体使用方法,请自行查阅)

总结: 上述 Swagger 接口声明使用方法还是较为笼统的,前文的赘述只是让读者们知道,优秀的前半部分,才能让后半部分继续保持优秀,前文中其他的详细内容,在此一笔带过,读者感兴趣的话可以自行搜索查阅。

二、Swagger 与自动化测试结合

如果没有明确本文议题,我差点就把本文题目更改为” Swagger 注解的使用” 了,下面,言归正传,本文是介绍 Swagger 与自动化接口测试的议题,自然要开始介绍我们测试是如何与 Swagger 特色技术接轨的 (敲黑板,说重点)

很久以前,传统测试在测试接口时,是根据研发提供的接口文档再结合接口测试工具,开展接口测试工作的,这也造成了沟通之间产生了成本,同时对于工程项目本身的变化,除研发外,亦是无感知的,除研发人员外没有他人有办法做到对工程内部接口统计、变化来做应对,亦没有一个长期可持续测试监控的应对方案

许久之后,技术在进步,Swagger 可以动态生成接口测试功能,方便了他人使用,基本做到了你好我好大家好的目的,但是 Swagger 只是提供了在线调试的功能,日常业务工程迭代后,Swagger 并没有记录变化,亦没有对业务接口做状态管理,更没有提供可持续接口用例测试的功能,由此启发,我们是否可以做一个兼具管理业务接口和可持续测试的用例模块?

据调研,果然真的行!

2.1 测试服务功能流程概述

测试项目功能维度,共为三个模块分别为:

• Swagger 接口项目
• Swagger 接口管理
• Swagger 测试用例

顾名思义,业务工程项目装着工程接口,在业务工程接口下,测试可以创建业务的接口测试用例 (是不是很绕嘴?),这样每次工程接口同步时,测试就可以及时获悉工程内接口的变化情况!

下图是服务化接口测试整体流程图:

功能流转图

让我们来逐条分析下数据流转步骤

• 1、首先.业务工程部署 (按照前文描述前半部分很美好的情况下),这样测试服务就可以稳定获取业务工程的接口信息
• 2、然后,测试服务会请求 ApiDoc 暴露的工程接口,获取当前业务存在的工程信息 (该工程必须是 Health 状态 *,后续会提到)

• 3、然后,工程项目的信息会有以下同步逻辑:

  • 若:ApiDoc 提供工程信息,测试数据库内未有该工程记录,则新增,Swagger 项目管理模块内,该工程名称背景色显示淡红色 (提示你有新工程创建)
  • 若:ApiDoc 提供工程信息,测试数据库内存在该工程记录,则根据工程 Desc、Host、BashPath、ternsOfService、Author 进行 md5 加密与 ApiDoc 提供的工程信息比对,判断是否发生数据变化,若存在变化,则该工程名称背景色显示淡蓝色,md5 值一致则默认背景色显示淡灰色
  • 若:该工程不是 Health 状态,或者 Nacos 未配置项目信息,Swagger 是解析不出来该工程信息的,则不同步 (重中之重)
  • 若:该工程暂时挂掉了,且期间发生接口用例同步,则测试服务默认为该工程为删除状态,背景色显示淡黄色 (不参加统一测试调度)

• 4、业务接口信息同步逻辑:

  • Swagger 同步时,若数据库内为存在 Swagger 提供的 A 工程的业务接口则接口管理模块该接口数据展示色淡红色
  • Swagger 同步时,根据测试库内存在的业务接口字段 method、tags、summary、description、params、headers、response、requests 进行 md5 加密,同时与 Swagger 提供的业务接口进行比对,md5 值相等则继续为淡灰色,md5 值不等变更为修改状态背景色显示淡蓝色
  • Swagger 同步时,若数据库内已记录业务接口,Swagger 提供的工程内未存在该记录接口时,则数据库记录业务接口状态变更为淡黄色 (不参加统一测试调度)

下图是测试服务从 Swagger 获取测试数据的数据状态流转

[数据状态流转图]

下图是测试服务器请求 APIDOC( Nacos 里已配置) 获取存在服务接口的工程样例,并获取工程下的接口信息 (取决于注解是否使用规范)

[数据请求流转图]

以上为业务接口数据同步逻辑,Swagger 同步设置亦不是一次性,而是每天都会从 Swagger 获取最新的数据情况,所以工程的健康稳定性是测试的强依赖点,测试者可以根据工程显示背景色和业务接口显示背景色来判断哪些接口是新增,哪些是修改,哪些是删除!

同步完业务接口,自然要在业务接口的基础上创建测试用例,测试用例和业务接口是多对一的组合,该部分内容属于接口测试范畴,诸位可自行查阅,在此不做过多讲解

2.2 接口测试用例管理介绍

介绍完数据流转,自然该轮到形影不离的模块使用了,此部分多为测试者维护测试用例之功能科普

按照之前所讲,数据流转,项目为先,对于使用 Swagger 项目功能模块是优先讲解的, 数据同步完成后,测试者可根据此模块获取数据同步后不同环境不同分支下最新的工程状态信息

根据此页面功能,可进入该工程内部 Swagger 文档模块,此模块亦可查询最新的服务接口数据信息,测试者操作服务 API 进行创建测试用例©,打标” 测试”√和” 无需测试” 状态” X

前文曾讲到,服务 API 接口对应的测试用例是 1 对 N 的情况,故在此可以创建多条测试用例

根据此页面功能,亦可进入该内部 Swagger 用例模块,可查询出服务 API 的接口测试用例,由于页面篇幅原因暂时只展示部分内容,对应的操作栏里有” 测试用例状态”、” 是否添加调度”、” 删除”、” 修改”

从操作栏内点击修改图标后,存在三个功能,分别为:用例描述、调试、文档

顾名思义,用例描述为测试用例的详细描述,譬如测试如何场景等等

调试,则为 API 服务请求,以及请求后的返回参数等,实时操作

文档:可展示服务 API 的详细展示 (此功能展示详细度取决于工程服务 API 注解详细度)

由此,工程内服务 API 信息一目了然的可以测试了

三、注意事项

阅读到这里的小伙伴们,是否有些劳累呢?再坚持坚持,不知诸位小伙伴们对前文提到的功能有何见解呢?

阅读过整篇文章的同学,肯定有所察觉,整个篇幅内多次强调过的注意事项:

• 执行规范,良好@API注解详细度才能推动后续步骤的快速进行,否则沟通的成本还不如原有的抒写接口文档来的便捷
• 工程稳定性,良好的工程稳定性,可以使服务 API 状态减少多变性,亦可以使测试用例达到调度数量最大化
• Service 层面的 API 用例,目前只能在 QA 和沙箱请求,灰度和线上危险系数很高
• Swagger 不仅仅只局限于 service 工程,一些 spring * * * 框架相关的 web 工程亦是支持, 有兴趣的小伙伴,可以自行修改自己的 Web 工程尝试 (其实作为测试者更应关注对于 WEB 工程的解析结果,毕竟测试是要站在用户的角度去考虑问题的)