写点什么

轻松完成接口测试及接口文档

作者:Xd
  • 2022 年 8 月 06 日
  • 本文字数:4398 字

    阅读完需:约 14 分钟

1.日常琐事逃不掉

作为一名后端开发工作者,多年来我的日常工作就是接口编码,接口测试,接口联调,接口文档编写。这四件事情就像四座大山直挺挺地压我的心头。

多年来我也一直在苦苦寻找着能提高接口测试联调效率的工具,最先了解到的是 postman 这款国外的 API 测试工具。它使用起来总体还算顺畅,日常接口自测的需求基本可以满足,但是鸡肋的团队协作能力,以及不能很好的生成接口文档,让我对它还是有所失望。接口文档的编写也是意见费事费力的事情,为了少写接口文档,我用上了 swagger(丝袜哥)。它的确可以很方便地生成在线文档。某种程度上解放了我编写文档的双手。但是呢?其不能很好的导出文档,严重依赖自身接口服务的缺点也是让我比较头疼。

我一直在想有没有一款能集 postman 和 swagger 的优点于一身的好工具呢?我苦苦寻觅,多年不得其果,一次偶然的机会,让我了解到了Apipost这款神器。那一刻我的真的有种踏破铁鞋无觅处,得来全不费工夫的感觉。下面就有请 Apipost 做一下自我介绍。

Apipost:大家好,我叫 Apipost,我来自种花家,我可以进行 POST,GET 等常见 HTTP 请求测试,同时,我也可以直接生成并导出漂亮的接口文档。当然了,我同样可以很方便的进行团队协作,大家可以在我上面轻松创建团队,管理项目。大家可以点击此链接找我玩哦,我的介绍完毕,谢谢大家。

2.开发实测是真香

2.1. 整体了解Apipost

为了满足客户的不同需求,Apipost 推出了 web 版以及客户端版两种不同的版本。

其中,web 版的链接地址是:

Apipost-基于协作,不止于API文档、调试、Mock​

客户端的下载地址是:下载中心-Apipost-中文版接口调试与文档管理工具

web 版和客户端版的操作基本一样,唯一的区别是 web 版只有网络在线才能使用,而客户端版离线就能使用。

客户端下载安装过程比较简单,在此我简单说下:

你这里可以根据自身的操作系统选择对应的安装包下载,安装包下载完成之后,按照安装提示操作即可顺利安装 Apipost 客户端。

step1.安装完成之后,首先需要点击登录按钮,只有登录成功了才能进行相关的操作,如果没有账号的话则需要先注册一个账号,不过比较友好的是 Apipost 支持微信扫码登录。

登录之后的会出现如下主界面窗口,Apipost 会自动给你的账号创建一个团队,并给该团队添加一个默认项目以及一些示例接口,真的爱了,爱了。

我这里将主界面窗口分为六大块,分别是:

(1)API 列表区:在这个区域我们可以新建接口,新建目录,导入接口以及项目,并且可以查看当前项目下的接口列表。

(2)主 tab 区:在这个区域我们进行分享列表查看,项目管理,团队管理,接口全流程测试等操作。

(3)设置区:在该区域我们进行 Cookie 的管理,分享项目,管理归档,设置全局参数,以及新建环境,这里的环境一般指的是实际开发中的开发环境,测试环境,现网环境等。

(4)接口操作区:在该区域我们可以给接口添加请求参数,填写接口地址,发送接口请求,当然也可以编写预执行脚本以及后执行脚本。

(5)脚本接口数据区:该区域主要展示接口请求的响应结果。当发送请求时则会展示实时响应,请求头,响应头,Cookie 这些信息,成功响应示例,错误响应示例是一个预制的数据。

(6)基础操作区:这个区域最常用的就是内置 Mock 字段变量以及控制台功能,当然也可以进行一些设置操作。我们可以在设置窗口中设置代理,添加 CA 证书,进行发送设置等操作。

在控制台中我们可以查看接口请求的完整信息,后面的演示中我们会多次使用到控制台。

2.2. 导入项目

相信很多小伙伴都在使用 postman,那么如何将 postman 中的项目迁移到 Apipost 上呢?我们只需要先在 postman 上导出项目,然后在 Apipost 上导入项目即可。

1.在 postman 上选中项目,右键,选中 Export 按钮导出项目。

2.在 Apipost 的 API 列表区中右键选择 导入项目。

3.项目导出成功之后选中当前团队,即可看到导入的项目。

2.3. 全局参数

实际开发中同一个项目的一批接口一般都有一些公共的请求参数。比如常见的 token 参数,项目下的每个接口(除登录接口外)请求时都需要在 head 中带上 token 参数,如果我们在每个接口上添加就太麻烦,这时候我们就可以设置一个全局的 token 参数。

1.如下新闻列表接口,在没有传入 token 参数之后,直接请求该接口会提示用户未登录。

2.接着我们点击全局参数 按钮,在全局 Header 中设置名为 token 的参数,这里暂时将 token 的值写死了,后面会介绍如何将全局参数设置成变量。

相比于 Postman 的全局变量设置,Apipost 支持设置的变量种类更多,支持的范围更广,Apipost 支持设置全局 Header,全局 Query,全局 Body,全局认证,全局的预执行脚本,以及全局的后执行脚本。

3.再次请求该接口的话,就可以看到能够正常请求到数据了。

2.4. Mock 参数设置

Mock 参数设置也是实际接口测试中经常需要用到的一个功能,最典型的就是在请求接口时传入当前的时间戳,或者一些随机数。如下图操作即可看到内置 Mock 变量列表。

这里我选择了一个日期的 Mock 变量,再次点击发送请求,点击控制台按钮,找到那个请求,查看 Request Body 即可看到设置的随机 date 参数。

如果内置 Mock 变量不满足需求,也可以点击更多 Mock.js 文档的按钮,查看你所想要的 Mock 函数。比如要生成随机的姓名,就可以直接复制上面的 @cname() 方法即可。


2.5. 预执行脚本

预执行脚本是一个接口请求发送前执行的脚本。我们可以通过预执行脚本执行 编写 JS 函数实现复杂计算;定义、获取、删除、情况环境变量以及全局变量;获取请求参数;动态添加、删除一个 header、query,body 请求参数等一系列操作。

Apipost 非常贴心地为我们提供了各种操作的脚本模板,这怎能让人不爱呢?

比如你需要设置一个全局变量,那么只需要点击设置一个全局变量按钮,它即可为我们生成 apt.globals.set("key", "value"); 这样的语句。

如下我定义了一个名为_random()的 js 函数,并定义了一个全局变量 random_var,然后在请求参数中定义设置该全局变量,发送请求后的结果如下图所示:


2.6. 后执行脚本

后执行脚本原理上与预执行脚本一致,不同的是它是在接口请求之后执行的。它主要用于设置断言脚本以验证测试用例。同时它还可以用于接口参数依赖的场景,比如业务接口需要获取登录接口返回的 token,这时候就可以在登录接口的后执行脚本中获取接口响应的 token,并设置 token 为全局变量。

1.设置断言

断言语句的格式一般类似这种 apt.assert(表达式代码); 比如:

apt.assert('response.json.code==10000');
复制代码


2.设置全局变量

通过 apt.variables.set("token", response.json.data.token);  语句可以获取响应体中的token值并设置全局变量token。
复制代码


需要使用全局变量时则需通过占位符{{token}}来接收这个全局变量的值,既可以在单个接口的请求头中设置,也可以在全局参数中进行设置。


2.7. 生成接口文档

自动生成漂亮的接口文档是我认为 Apipost 最实用的一个功能之一,相比于 Postman 鸡肋的生成接口文档功能,Apipost 做的就要好太多了。在前后端分离的大背景下,接口文档是前后端联调标准语言,一个清晰准确的接口文档可以大大提高前后端联调的效率。Apipost 生成接口文档的方式也非常简单,只需要分享一下就可以了。

1.分享单个接口

生成单个接口的接口文档,只需要打开某个接口,点击分享按钮。


进入接口文档的分享窗口后,复制外网链接在浏览器上打开即可预览接口文档,在分享时我们可以选择文档的有效期,当然,只能在线预览接口文档还是远远不够的,Apipost 还贴心的推出了接口文档导出功能。此刻我只想说:听我说,谢谢你,因为有你,温暖了四季。

这里我选择导出 Word,文件下载之后,打开导出的 Work 文档,真的很哇塞呀,这文档完完全全达到了交付标准。

2.生成整个项目的全部接口文档

如果我们想生成整个项目的全部接口文档,那也很简单,只需要点击分享项目按钮即可。

Apipost 的接口文档分享出去之后,在你再次分享之前文档是不会被改变的,前端人员再也不用担心文档莫名其妙的就变了,或者在线文档不能稳定访问等问题了。

2.8. 团队协作

Apipost 的团队协作功能也是一个非常突出的亮点功能。在项目越来越庞大的今天,任何一个大型项目都不是一个人单打独斗完成的,都是靠团队协作开发的。团队协作功能的重要性不言而喻,让我们想象一个场景:你同事的接口需要依赖你写的接口,你把接口测试完成之后,你同事还需要在在他自己的电脑上模拟测试一遍你的接口,这样是不是有点繁琐。

通过团队协作功能,你同事就可以直接利用你测试好的接口用例,这样是不是非常的 nice 呢?下面就简单介绍下如何使用团队协作功能。

1.点击团队按钮。

点击之后会跳转到网页端的团队页面,在该页面中我们可以邀请成员,管理团队,管理项目。这里我要求了飞哥二号加入到我的团队,并给他分配了可操作的项目。

邀请完成之后就可以在团队管理里看到被邀请的协作人员。被分配的协作人员权限可以是读写权限(读写工位),也可以是只读权限(只读工位)。

当然,我们也可以在项目管理里也可以添加协作人员,需要注意的是,如果不把协作人员加入到某项目中,那么该协作人员是看不到该项目的。

协作者账号飞哥二号登录之后,它不仅可以看到自己团队下的项目,还能查看码农飞哥团队下的项目。

2.9. 全流程集成测试

前面都是针对单个接口进行介绍的,但是在实际开发中我们需要对同一个流程下的多个接口进行全流程的集成测试,可以说集成测试又是实际开发中的一个硬性刚需。Apipost 同样为我们想到了,它提供了方便好用的集成测试功能。

我们只需要点击测试按钮,新建流程,选择需要批量测试的接口,点击开始测试即可轻松完成多个接口的集成测试。

3.货比三家我最棒

整体体验下来,我的感觉非常不错的,对比 postman,Apipost 的优势不要太明显,我认为其主要有如下四点优势:

1.上手快

一个从没使用过 Apipost 的小白,仅仅只需要花上半天的时间就能熟练掌握其使用。它详细清晰的使用文档,基本上只要懂汉语的小伙伴就能马上上手。于此同时,官方还贴心的推出了 Apipost 教学视频,手把手教您使用 Apipost,真的不要太友好哦。

2.生成漂亮的接口文档

编写接口文档是每一个后端开发都绕不过的一道坎,曾几何时,我也被接口文档编写折磨的不要不要的。虽然 Swagger 解决了我的部分烦恼,但是其不能导出漂亮的 Word 文档也是让我很头疼不已,Apipost 就完美地解决了这个问题。

3.团队协作

团队协作又是一个痛点,在公司里你永远不是一个人在战斗,你的上游有产品经理,下游有测试小姐姐,还有前端开发人员与你并肩作战。所以,团队之间的沟通协作尤其重要。Apipost 的团队协作功能真正做到了团队内部的项目实时共享,上下游无缝协同。

4.全流程集成测试

Apipost 完美的支持整个项目全流程集成测试,也满足了实际开发中的一个硬性刚需。

4.总结升华

自从有了国产的 Apipost 之后,我再也不用担心哪天突然被国外卡脖子,用不了 postman,耍不了 Swagger 了。它实实在在的可以提高我们的开发测试效率,提升团队协作能力,期待Apipost可以推出更多更实用的功能。我可以拍着胸脯说 Apipost 完全可以替换掉 postman 以及 Swagger。如此好用的一款软件,难道不值得我们大力推广么?

用户头像

Xd

关注

还未添加个人签名 2022.03.28 加入

还未添加个人简介

评论

发布
暂无评论
轻松完成接口测试及接口文档_Java_Xd_InfoQ写作社区