宝藏发现之API接口高效协作神器Apifox

概述

背景

Apifox官方地址 https://www.apifox.cn/

前面文章我们已经围绕微服务展开,缺少一个关键前置流程,那就是API接口设计,而在API接口设计开始前本篇先推荐一个非常好用的国人开发工具,它就是Apifox,免费只需注册就可使用,如需私有化部署再购买,绝大部分人使用场景都可直接使用免费版,无任何限制,相当给力。相信大部分API设计会采用Swagger或Yapi管理 API 文档,后端开发人员肯定是使用过Postman来做API接口联调(界面是英文版,如果要汉化还得另外处理)、而同时前端开发人员也会使用Mock.js的Mock API 来模拟接收后端返回数据进行同步开发,测试人员使用JMeter做API自动化测试等等。

宝藏发现之API接口高效协作神器Apifox_第1张图片

不用惊讶,Apifox提供一整套解决方案,,Apifox = Postman + Swagger + Mock + JMeter。Apifox 通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好 API 文档,API 调试、API 数据 Mock、API 自动化测试就可以直接使用,无需再次定义;API 文档和 API 开发调试使用同一个工具,API 调试完成后即可保证和 API 文档定义完全一致。高效、及时、准确!

宝藏发现之API接口高效协作神器Apifox_第2张图片

功能特性

官网说明特性包含API 文档设计、API 调试、API 自动化测试、API 数据 Mock、CI 持续集成、数据库操作、自动生成代码、支持 HTTP、TCP、RPC、数据导入/导出、团队协作。如下为官网首页部分功能特性,详细可以查阅官网

宝藏发现之API接口高效协作神器Apifox_第3张图片

Apifox前期可称为Apifirst,实现了以下几个亮点功能

  • 后端、前端、测试团队可以同步开始工作,而不需要互相等待;
  • 使用基于API的自动Mock、代码自动生成和自动化测试工具,大幅提升开发效率;
  • 开发的各个角色都会获得更好的工作体验;
  • API可以在不同的项目中重复使用,提高开发效率;
  • 新人更容易熟悉项目,方便团队规模的扩大;
  • 与外部团队的协作也更加顺畅。

团队协作流程

  • 设计阶段

    • 根据需求文档讨论确定接口设计思路。
    • 接口设计者在Apifox上定义好文档初稿。
    • 接口评审环节,前后端一起评审、完善后接口文档,定好接口用例。
  • 开发阶段

    • 前端 使用系统根据接口文档自动生成的 Mock 数据进入开发,无需手写 mock 规则。
    • 后端 使用接口用例 调试开发中接口,只要所有接口用例调试通过,接口就开发完成了。如开发过中接口有变化,调试的时候就自动更新了文档,零成本的保障了接口维护的及时性。
    • 后端 每次调试完一个功能就保存为一个接口用例
    • 测试人员 直接使用接口用例测试接口。
  • 联调和测试阶段

    • 所有接口开发完成后,测试人员(也可以是后端)使用集合测试功能进行多接口集成测试,完整测试整个接口调用流程。
    • 前后端 都开发完,前端从Mock 数据切换到正式数据,联调通常都会非常顺利,因为前后端双方都完全遵守了接口定义的规范。
    • 测试可以使用测试套件进行自动化回归测试和性能测试。

安装

安装

官网提供客户端安装版本和 Web 端版本使用,官网也推荐使用客户端版本,支持Windows、MacOS、Linux,开始下载 Windows(64 位)的版本,安装即可。

文档

官网文档地址 https://www.apifox.cn/help/

Apifox B站视频 https://space.bilibili.com/1102302972?spm_id_from=333.337.search-card.all.click

官方提供非常详细的使用文档,且部分还有视频教程,此外apihub是一个开放 API 共享平台,可以找到更多公开 API 项目。Apifox在bilibili上也有一些教程视频合集。

注册

双击启动Apifox后,可通过邮箱注册一个账号,登录后主页提供我的团队、APIHub、我的收藏、最近访问四大块功能。在示例团队里有一个宠物店的示例项目,可以详细参考学习,我们下面则以一个实际操作流程来学习下Apifox整体使用。

实战示例

团队管理

第一步我们先创建团队,名称为ITXS团队,点击保存。

宝藏发现之API接口高效协作神器Apifox_第4张图片

  • 团队名称可以修改,团队可以移交(将团队的所有者权限移交给其他成员)和解散(务必谨慎,解散后无法找回)。
  • 权限分为团队权限和项目权限。团队权限指成员对团队操作的权限,项目权限指成员对项目操作的权限。详细权限可以查阅官网。
    • 团队角色:所有者、管理者和普通用户。
    • 项目权限:管理员、普通成员、只读成员、禁止访问的角色。
  • 团队角色分所有者、管理者和普通用户。

邀请成员可设置其团队的权限和对应项目的项目权限

宝藏发现之API接口高效协作神器Apifox_第5张图片

受邀请成员在通知栏中点击接受即可

宝藏发现之API接口高效协作神器Apifox_第6张图片

在团队成员权限中可以修改成员的权限和移除成员。

新建项目

创建选课系统示例项目

宝藏发现之API接口高效协作神器Apifox_第7张图片

  • 在团队下的项目可以修改项目名称、克隆项目、移动项目、删除项目、收藏项目(在我的收藏中可以快捷找到)
  • 点击直达项目,启动Apifox直接进入到这个项目。
  • 新窗口打开,这个好用,如果我们同时有多个项目的话可以打开多个项目窗口,同时主窗口也在,刚开始我们开可以一边参考示例团队的示例项目。

数据模型

数据模型是可复用的数据结构。在设计数据结构时可以在数据类型直接选择已经定义好的数据模型。管理数据模型,在使用数据模型前,需要先建立可复用的数据结构。如下图,根据项目需要,可以先在数据模型下新建,也可以简单的管理不同数据模型间的关系。数据模型之间也可以相互引用。

当下接口需要部分引用数据模型时,可以在引用的情况下修改,并且不影响原数据模型

  • 当不需要数据模型中的某个字段时,可以点击隐藏字段,则接口文档中就不会显示了
  • 当需要对数据模型中的某个字段,特殊编辑时,可以点击取消关联。当然后续也可以恢复关联
  • 可以引用多个数据模型,并支持数据模型之间拖拽排序

点击直达进入选课系统示例项目,接口创建学生分组,数据模型中也创建基础和学生分组,在基础分组中通过在根节点上点击+号逐个字段创建好系院数据模型,最后点击保存Depart数据模型。

宝藏发现之API接口高效协作神器Apifox_第8张图片

基础分组继续创建专业数据模型,在Depart数据模型是哪个选择复制,输出专业信息,最后点击保存Major数据模型。

宝藏发现之API接口高效协作神器Apifox_第9张图片

基础分组继续创建班级数据模型,点击中间的JSON/XML智能识别/快捷导入,确定后可快捷生成数据模型的字段和推断出字段类型

宝藏发现之API接口高效协作神器Apifox_第10张图片

创建学生数据模型

宝藏发现之API接口高效协作神器Apifox_第11张图片

全局响应

全局响应主要用来实现返回响应的复用。通常不同接口在某些情况下会返回相同的数据结构,如资源不存在(404)没有访问权限(401)等,这些建议设置为全局响应,避免重复编写,放方便统一管理。

项目设置中全局响应创建全局响应,填写如下

宝藏发现之API接口高效协作神器Apifox_第12张图片

再多创建几个全局响应

宝藏发现之API接口高效协作神器Apifox_第13张图片

接口管理

查询接口

学生信息查询接口

接口设计即定义接口文档规范(如接口路径、参数、返回值、数据结构等)

  • 接口设计:即 新建接口 界面或接口详情里的 编辑 界面,用途是 定义接口文档规范,而不是 运行 接口,所以该界面是只能定义接口基本信息、参数名及参数说明等,而不能设置参数值参数值前置脚本/后置脚本 等信息请在接口运行界面或接口用例界面填写。
  • 接口运行:即接口详情里的 运行 界面,用途是 临时调试接口运行 完后,需要点击保存为用例,才能将填写的 参数值前置脚本/后置脚本 等信息保存下来;否则关闭 tab 后,这些信息将会丢失。

接口路径

  • 接口路径 建议不要包含 HTTP 协议及域名,这部分建议在 环境管理 的前置URL里设置,接口调试时的 URL 会自动加上当前环境的前置URL
  • 特殊情况需在接口路径要带上HTTP 协议及域名的,系统也能支持,但不建议这么做。接口调试时,系统如检测到接口路径是以http://https://起始的,会自动忽略当前环境里前置 URL。
  • Apifox 中的 Path 参数是以大括号包裹起来表示,而非冒号起始表示。正确示例/pets/{id}错误示例/pets/:id
  • 接口路径 不可包含Query 参数(即 URL 中 ?后的参数),Query 参数在下方请求参数部分填写。

在学生分组下创建查询学生信息接口

宝藏发现之API接口高效协作神器Apifox_第14张图片

点击修改文档,在根节点下添加响应的字段数据,点击保存按钮

宝藏发现之API接口高效协作神器Apifox_第15张图片

添加一个响应示例,点击自动生成,可以看到Apifox已经给我们Mock出来很多正常使用的数据。

宝藏发现之API接口高效协作神器Apifox_第16张图片

点击运行,切换为Mock服务,点击发送,响应数据内容如下,这个是Mock出来的数据,最后点击保存为用例为后续测试复用。

  • 在接口运行的时候,接口路径、参数名会自动从接口设计读取,无需手动输入,参数值默认会读取接口设计里的示例值,可手动修改。
  • 填写好参数后,点击发送按钮即可运行。
  • 保存为用例是将当前填写的参数保存起来,方便下次或者其他人用来调试接口。
  • 保存为用例后,接口用例会显示在左侧树状菜单里接口的下一级。
  • 接口用例是非常有用的,建议每次运行后都保存为用例,后续用接口用例来调试接口是非常高效的。
  • 通常一个接口会有多种情况用例,比如参数正确用例、参数错误用例、数据为空用例、不同数据状态用例等等。
  • 返回响应是用来给系统校验接口请求后返回的数据是否符合对应 Response 里定义的数据结构,免去人眼识别,提高效率和准确性。
  • 数据结构校验结果系统会根据选择的返回响应的数据结构,自动分析运行后返回的数据是否正确,并且给出详细的错误提示。
  • 断言:后置操作支持添加断言,可对接口返回的数据(或响应时间)设置断言,判断是否符合预期。
  • 提取变量后置操作支持添加提取变量,可从接口返回结果里提取数据,设置到变量(临时变量/环境变量/全局变量),方便其他接口运行的时候直接使用。

宝藏发现之API接口高效协作神器Apifox_第17张图片

选择全局响应记录不存在,点击发送测试,结果如下,最后保存为记录不存在用例。

宝藏发现之API接口高效协作神器Apifox_第18张图片

回到文档TAB页,可以看到已经MOCK区域有两条记录

宝藏发现之API接口高效协作神器Apifox_第19张图片

复制URL我们直接到浏览器上访问下,可以看到已经在本地启动Mock服务

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-3LUSnGoD-1651340301671)(F:\creation\markdown\article\宝藏发现之API接口高效协作神器Apifox\宝藏发现之API接口高效协作神器Apifox.assets\image-20220430195909497.png)]

实时更新接口的状态,不同状态的颜色不同,有利于团队协助进行,相应人员可以根据状态进行筛

宝藏发现之API接口高效协作神器Apifox_第20张图片

需要更多状态管理时可以到项目设置,功能设置中借楼状态进行设置

宝藏发现之API接口高效协作神器Apifox_第21张图片

创建期望

创建记录不存在的测试用例,在接口中切换高级Mock,点击新建期望,设置路径参数为3时作为记录不存在

宝藏发现之API接口高效协作神器Apifox_第22张图片

宝藏发现之API接口高效协作神器Apifox_第23张图片

新建接口

学生信息新建接口

新建学生信息接口,为Post请求,填写Body数据,在返回响应的全局响应中关闭,状态码为201,点击保存(记得修改文档后一定要点击保存再操作运行)

宝藏发现之API接口高效协作神器Apifox_第24张图片

点击运行并保存为成功用例

宝藏发现之API接口高效协作神器Apifox_第25张图片

修改接口

修改学生信息

创建修改学生信息接口为PUT类型,使用json导入参数,保存为接口

宝藏发现之API接口高效协作神器Apifox_第26张图片

创建一个验证错误返回响应

宝藏发现之API接口高效协作神器Apifox_第27张图片

验证错误响应

宝藏发现之API接口高效协作神器Apifox_第28张图片

删除接口

删除学生信息接口

创建删除学生信息接口类型为DELETE,保存

宝藏发现之API接口高效协作神器Apifox_第29张图片

保存为成功用例接口

宝藏发现之API接口高效协作神器Apifox_第30张图片

在返回响应成功(200)添加code字段,添加响应示例,点击自动生成,并保存为成功用例

宝藏发现之API接口高效协作神器Apifox_第31张图片

创建快捷请求

快捷请求可以输入完整的URL,填写相关的参数

宝藏发现之API接口高效协作神器Apifox_第32张图片

自动化测试

测试用例

添加用例有两种方式:从接口导入从接口用例导入 (推荐)

  • 从【接口】导入:根据接口参数自动生成一个用例,其参数值为空,需要手动填写。
  • 从【接口用例】导入:有两种模式复制绑定。将接口用例以复制的方式导入,接口用例里的参数也会一同复制过来,和原来用例数据相互独立,各自改动后互不影响。将接口用例以绑定的方式导入,会直接引用原来的用例,两边的改动都会相互实时同步。
  • 从接口导入后,需要手动设置接口参数,否则运行的时候,接口参数是空的。
  • 从接口用例导入后,会同步导入接口用例里的参数,会方便很多。

创建测试用例

宝藏发现之API接口高效协作神器Apifox_第33张图片

点击详情,从接口用例导入数据,也可以从接口中导入用例

宝藏发现之API接口高效协作神器Apifox_第34张图片

导入,点击运行

宝藏发现之API接口高效协作神器Apifox_第35张图片

查看测试结果

宝藏发现之API接口高效协作神器Apifox_第36张图片

测试套件

测试套件测试用例的集合,每个测试套件包含多个测试用例。主要用途:

  • 实现测试用例的复用。
  • 业务流程复杂时,可避免将所有步骤都写在单个用例里,防止造成单个用例里的步骤过多,难以管理。

选择一组测试用例,运行输出测试结果

宝藏发现之API接口高效协作神器Apifox_第37张图片

性能测试

  • 运行测试用例的时候,设置线程数大于1即可实现性能测试。
  • 线程数即同时【并发】运行的线程数,每个线程都会按顺序运行选中的所有步骤。
  • Apifox CLI 是 Apifox 的命令行运行工具,主要用来做持续集成和压力测试,其压力测试功能目前正在开发中,敬请期待!
  • 测试用例测试套件可以导出JMeter`格式数据,然后可以导入 JMeter 做性能测试。

测试数据

测试用例测试套件支持测试数据集。当用例或套件运行时,系统会循环运行数据文件里所有的数据集,并且会将数据集里的数据赋值给对应的变量。

  1. 每个数据集可包含多个变量,接口运行时 使用变量 的地方会读取对应的值(变量优先级:临时变量 > 测试数据变量 > 环境变量 > 全局变量)。
  2. 可创建多个数据集,系统会遍历运行所有的数据集(每个数据集都会被运行一次)。
  3. 数据集云端同步,成员之间共享测试数据。
  4. 可根据不同环境设置不同的数据集。

测试报告

运行完成后,如图所示,可以看到哪些接口没有通过测试,可以点击对应的接口展开详情;点击更多详情,可以查看该接口的运行结果,方便定位问题。运行结束后查看之前的测试报告,也可以导出。

宝藏发现之API接口高效协作神器Apifox_第38张图片

Mock

功能说明

Mock 功能可以根据接口/数据结构定义Mock规则配置Mock 期望配置,自动生成模拟数据,且使用者可以根据需要灵活构造各种结构的接口数据。通常情况 Apifox 零配置即可生成非常人性化的 mock 数据:

  • Apifox 根据接口定义里的数据结构、数据类型,自动生成 mock 规则。
  • Apifox 内置 智能 Mock功能,根据字段名、字段数据类型,智能优化自动生成的 mock 规则。如:名称包含字符串imagestring类型字段,自动 mock 出一个图片地址 URL;包含字符串timestring类型字段,自动 mock 出一个时间字符串;包含字符串citystring类型字段,自动 mock 出一个城市名。
  • Apifox 根据内置规则(可关闭),可自动识别出图片、头像、用户名、手机号、网址、日期、时间、时间戳、邮箱、省份、城市、地址、IP 等字段,从而 Mock 出非常人性化的数据。
  • 除了内置 mock 规则,用户还可以自定义规则库,满足各种个性化需求。支持使用 正则表达式通配符 来匹配字段名自定义 mock 规则。

零配置一些常见字段已经自动mock数据

宝藏发现之API接口高效协作神器Apifox_第39张图片

Mock 语法

Apifox Mock 语法完全兼容[Mock.js(数据占位符方式),并扩展了一些 Mock.js 没有的语法(如国内手机号 @phone)。如现有 Mock 语法无法满足需求,建议使用 正则表达式 @regexp来实现灵活的定制。正则表达式基本能满足各种特殊场景的需求。

基本写法

写法 说明
@起始的字符串 调用 Mock 语法规则生成对应的数据。 如生成的数据类型和定义的数据类型不一致,则会自动转换。
@起始的字符串 数据类型为string时,原样输出。 其他数据类型,会将字符串自动转换到对应的数据类型。
特殊字符:null 数据类型允许为null 时,输出null。 否则自动转换,如数据类型为string,输出"null"
特殊字符:true 数据类型为boolean 时,输出true。 否则自动转换,如数据类型为string,输出"true"。
特殊字符:false 数据类型为boolean 时,输出false。 否则自动转换,如数据类型为string,输出"false"。

自动转换 是使用 javascript 语言默认数据转换方法进行转换。其他详细可以查阅官网

高级MOCK

定义 mock 规则,前面我们接口中已使用自定义mock规则,针对字段Mock设置里选择,还可以像postman一样的自定义脚本

宝藏发现之API接口高效协作神器Apifox_第40张图片

  • 数据字段高级设置里设置的最大值最小值枚举值Parttenformat,也会作为 Mock 规则使用。
  • 高级 mock 的是最灵活的 mock 方式,可实现灵活的自定义数据结构(不受接口数据结构限制),且可以根据不同的请求参数值返回不同的数据设置位置:接口详情-高级 Mock
  • 优先级说明:请求 Mock 数据时,规则匹配优先级:高级 Mock 里的期望 > 自定义 Mock 脚本。如果匹配到了高级 Mock 里的期望,则不调用自定义 Mock 脚本

智能MOCK

  • 智能mock:当接口设计的返回 Response (或数据模型) 里的字段未配置 mock 规则时,系统会自动使用智能 Mock 规则来生成数据,以实现使用时零配置即可 mock 出非常人性化的数据。设置位置:项目设置-智能 Mock 设置自定义规则内置规则
    • 自定义规则:用户可新建自定义规则,满足各种个性化需求。支持使用 正则表达式通配符 来匹配字段名自定义 mock 规则。
    • 内置规则:系统内置常用 mock 规则库,可自由决定是否开启内置规则。
    • 优先级:自定义规则优先级高于内置规则,可添加自定义规则来覆盖系统内置规则。

智能Mock我们在前面查询接口的创建期望也简单介绍了,总体说MOCK功能是非常的强大。

生成在线文档

在 API 开发、沟通、协作中,逻辑上是以 API 文档为标准的,但实际操作中,存在以 Word、PDF 格式的文件传来传去的问题。为此我们提倡以在线文档的形式,提高团队之间的沟通效率,在线分享里新建分享

宝藏发现之API接口高效协作神器Apifox_第41张图片

创建后复制链接发给其他团队就可以使用了

宝藏发现之API接口高效协作神器Apifox_第42张图片

标签功能

接口修改文档中设置标签,输入则增加标签,保存,然后再左侧可以根据标签进行筛选。

宝藏发现之API接口高效协作神器Apifox_第43张图片

新建分享中可以指定标签设置分享范围

宝藏发现之API接口高效协作神器Apifox_第44张图片

环境管理

一个项目在不同的阶段会处于不同的环境中,比如开发环境测试环境生产环境,通常不同的环境有不同的前置 URL接口参数值等。因环境不同而频繁的更改接口前置 URL 及参数,是非常的麻烦的。 Apifox 的环境管理功能,只需在不同的环境设置不同的前置 URL 及参数,在不同环境中测试时,直接切换环境即可。如果默认环境不够用还可以新建环境。

快速切换前置URL,在管理环境比如在测试环境里添加服务,如学生和老师都有不同域名,点击保存

宝藏发现之API接口高效协作神器Apifox_第45张图片

回到查询学生信息接口修改文档,我们看到服务(前置URL)可以选择手动绑定学生服务

宝藏发现之API接口高效协作神器Apifox_第46张图片

这是在测试环境运行可以看到整个请求已经带上前置URL了

宝藏发现之API接口高效协作神器Apifox_第47张图片

后置操作

后置操作支持添加断言,可对接口返回的数据(或响应时间)设置断言,判断是否符合预期。

在运行中后置操作中添加后置操作,断言名称存在,保存用例

宝藏发现之API接口高效协作神器Apifox_第48张图片

运行查看结果,显示断言结果已存在,前置操作也是如此

宝藏发现之API接口高效协作神器Apifox_第49张图片

  • 后置操作支持添加提取变量`,可从接口返回结果里提取数据,设置到变量(临时变量/环境变量/全局变量),方便其他接口运行的时候直接使用。
  • 前置操作后置操作支持添加数据库操作,可读写数据库数据,查询结果可在接口请求参数、断言、自定义脚本等场景中使用。目前支持MySQLSQL ServerOraclePostgreSQL,未来会支持更多数据库类型。
  • 使用变量时,读取对象或数组类型变量里的属性值写法为{{allUser[0].name}}{{user.name}},遵循JSON Path语法规范,只需将JSON Path里的$符号替换为变量名既可。

环境变量 / 全局变量 / 临时变量

和编程语言类似,变量是允许在多个地方重复使用的值。不同的接口用例(请求参数、脚本等)可以引用相同的变量值,只需要更改一次变量值,就能改变所有引用了该变量的相关值。使用变量可以大幅提升工作效率。

宝藏发现之API接口高效协作神器Apifox_第50张图片

在新建学生信息结构修改文档,增加body参数,在请求参数的示例值的位置,鼠标移动到输入框上时,会显示一个魔法棒的图标(动态值有动态变量、常量、变量等设置),选择或者填入变量名,保存后点击运行

宝藏发现之API接口高效协作神器Apifox_第51张图片

在实际请求查看到token的值为全局变量设定的值

宝藏发现之API接口高效协作神器Apifox_第52张图片

其他功能

官方还提供很多其他的功能,如动态变量、随机参数、全局参数、socket报文接口、导入数据、导入抓包数据、导出数据、代码生成、接口之间传递数据、使用脚本、持续集成、插件等等,这些有兴趣可以前往官网继续学习,好了,本篇就先到这里

**本人博客网站 **IT小神 www.itxiaoshen.com

你可能感兴趣的