Apifox快速上手

前言

其实大家都知道 API 文档先行的重要性，但是在实践过程中往往会遇到很多困难。

程序员最讨厌的两件事：1. 写文档，2. 别人不写文档。大多数开发人员不愿意写 API 文档的原因是写文档短期收益远低于付出的成本，然而并不是所有人都能够坚持做有长期收益的事情的。

作为一个前后端分离模式开发的团队，我们经常会看到这样的场景：前端开发和后端开发在一起热烈的讨论“你这接口参数怎么又变了？”，“接口怎么又不通了？”，“稍等，我调试下”，“你再试试…”。

那能不能写好 API 文档，大家都按文档来开发？很难，因为写文档、维护文档比较麻烦，而且费时，还会经常出现 API 更新了，但文档还是旧的，各种同步不一致的情况，从而耽搁彼此的时间。

团队原来的工作模式

API 设计人员使用 Swagger 写 API 文档
前端开发 使用 mock.js mock 假的 API 数据
后端开发 使用 Postman 调试 API
测试人员 使用 JMeter 测试 API

存在的问题

我们团队是前后端同步进入开发的，不能等后端开发完了才出接口文档，前端再进入开发，所以使用后端代码注释自动生成 Swagger 不适合我们。

写 Swagger 文档效率很低，并且有学习门槛，让团队所有人都熟练手写 Swagger 文档是不现实的，更何况团队不停有新人进来。

开发人员在 Swagger 定义好文档后，接口调试的时候还需要去 Postman 再定义一遍。

前端开发 Mock 数据的时候又要去 mock 工具里定义一遍，手动设置好 Mock 规则。

测试人员需要去 JMeter 定义一遍。

前端根据 mock 工具出来的数据开发完，后端根据 Swagger 定义的接口文档开发完，各自测试测试通过了，本以为可以马上上线，结果一对接发现各种问题：原来开发过程中接口变更，只修改了 Swagger，但是没有及时同步修改 mock。

同样，测试在 JMeter 写好的测试用例，真正运行的时候也会发现各种不一致。

开发过程，经常会有发现开始定义的接口文档有不合理的地方，需要临时调整，经常出现接口改了，但是文档没有更新。

时间久了，各种不一致会越来越严重。

如何解决

要做到写文档和及时维护文档的短期收益就能远高于付出的成本，无非两个方向：

1 2	1. 降低写文档的成本 2. 增加写文档后的收益

鉴于此，我们设想如果有一款工具做到以下这些是不是就非常爽了？

1.以完全可视化的界面来编写文档，并且是零学习成本，新人 一来就能上手。

2.可以通过接口文档定义的数据结构自动 mock出数据，而无需 前端开发 再写mock规则，直接开工。

3.后端开发 在接口文档基础上调试接口，而无需在去Postman上调试；接口如有变化，调试的时候就自动更新了文档，零成本的保障了接口维护的及时性；自动根据文档校验数据结构，无需肉眼校验，无需手动写断言。

4.后端开发 每次调试完一个功能就保存为一个接口用例。

5.测试人员 直接使用接口用例测试接口。

6.测试人员 更加接口文档自动生成测试用例，然后像JMeter一样在直接在上面测试。

7.根据接口文档定义的数据结构，自动生成前后端的数据模型代码。

最佳实践

1.前端（或后端）在 Apifox 上定好 接口文档 初稿。

2.前后端一起评审、完善 接口文档，定好 接口用例。

3.前端使用 Apifox 自动生成的 **Mock 数据 **进入开发，而无需手写 Mock规则，直接开工。

4.后端使用 接口用例 调试开发中接口，系统根据接口文档的定义 自动校验 返回的数据是否正确，只要所有接口用例调试通过，接口就开发完成了。

5.后端开发完成后，测试人员（也可以是后端）使用 集合测试 功能进行多接口集成测试，完整测试整个接口调用流程。

6.前后端都开发完，前端从 Mock 数据 切换到 正式数据，联调通常都会非常顺利，因为前后端双方都完全遵守了接口定义的规范。

一.安装运行Apifox

1.1安装

双击安装Apifox-2.2.34.exe

1.2扫码注册登录

1.3加入团队

向团队的管理员申请加入团队的链接，点击链接加入团队。

1.4完成

二.IDEA插件安装使用

2.1 介绍

Apifox IDEA 插件（Apifox Helper）主要用于 IDEA 项目快速生成 API 文档，并同步到 Apifox，代码零入侵。

基于 javadoc（Java）、KDoc（Kotlin）、ScalaDoc（Scala）解析 API 文档。
支持 Swagger 注解
注意：可以在保持代码零侵入的情况下得到相当完整的 API 文档，但是特殊的需求还是需要部分特殊的注释/注解配合，注释规范说明。
该插件基于 easy-api 定制开发，感谢 easy-api 作者

2.2 功能特性

导出 API 文档到 Apifox
导出 Markdown 格式 API 文档
在 IDEA 中直接发起 API 请求

2.3 安装

从 IDEA plugins 中搜索安装

打开 IDEA > Preferences(Settings) > Plugins ，搜索 Apifox Helper

2.4 获取项目ID

打开项目设置——基本设置，复制项目 ID

2.5获取访问令牌

Apifox 个人访问令牌：获取访问令牌

2.6基础配置

安装插件后，进入设置界面 Preferences(Settings) > ApifoxHelper

填写Apifox 服务器地址: 填写 Apifox API 服务地址，SaaS 版默认为 https://api.apifox.cn
填写Apifox 个人访问令牌：获取可参考文档获取访问令牌
填写模块项目 ID 配置: 代码模块名和项目 ID 的映射关系配置，其中项目 ID 的获取可参考文档获取项目 ID

模块项目 ID 配置:

每个 Module 都需指定一个项目 ID，可选指定目标目录名。

如下填写，表示的是 mall-admin 和 mall-search 模块都导入到项目 2051427 且都是导入到根目录。

1 2	mall-admin:2051427 mall-search:2051427

如下填写，表示的是 mall-admin 和 mall-search 模块都导入到项目 2051427，分别导入到 管理后台、搜索目录下。

1 2	mall-admin:2051427,管理后台 mall-search:2051427,搜索

多级目录用/分割，如下填写，表示的是 mall-admin 和 mall-search 模块都导入到项目 2051427，分别导入到商城/后台管理、商城/商城搜索目录下。

1 2	mall-admin:2051427,商城/后台管理 mall-search:2051427,商城/商城搜索

2.7同步接口到 Apifox

同步模块内所有接口

在模块目录上的右键菜单中选择 Upload to Apifox

同步 controller 文件内所有接口

在代码编辑区域的右键菜单中选择 Upload to Apifox

同步选择部分接口

在模块目录上或代码编辑区域的右键菜单中选择 Export API

选择想要同步的单个或部分接口，回车执行同步请求

三.Apifox介绍

3.1 Apifox 定位

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。

通过一套系统、一份数据，解决多个系统之间的数据同步问题。只要定义好接口文档，接口调试、数据 Mock、接口测试就可以直接使用，无需再次定义；接口文档和接口开发调试使用同一个工具，接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确！

3.2 Apifox 宗旨

节省研发团队的每一分钟！

3.3 Apifox 功能

接口设计：Apifox 接口文档遵循 OpenApi 3.0 (原 Swagger)、JSON Schema 规范的同时，提供了非常好用的可视化文档管理功能，零学习成本，非常高效。并且支持在线分享接口文档。

数据模型：可复用的数据结构，定义接口返回数据结构及请求参数数据结构（仅 JSON 和 XML 模式）时可直接引用。支持模型直接嵌套引用，直接 JSON/XML 智能导入，支持 oneOf、allOf 等高级组合模式。

接口调试：Postman 有的功能，比如环境变量、前置/后置脚本、Cookie/Session 全局共享等功能，Apifox 都有，并且比 Postman 更高效好用。接口运行完之后点击保存为用例按钮，即可生成接口用例，后续可直接运行接口用例，无需再输入参数，非常方便。自定义脚本 100% 兼容 Postman 语法，并且支持运行 javascript、java、python、php、js、BeanShell、go、shell、ruby、lua 等各种语言代码。

接口用例：通常一个接口会有多种情况用例，比如参数正确用例、参数错误用例、数据为空用例、不同数据状态用例等等。运行接口用例时会自动校验数据正确性，用接口用例来调试接口非常高效。

接口数据 Mock：内置 Mock.js 规则引擎，非常方便 mock 出各种数据，并且可以在定义数据结构的同时写好 mock 规则。支持添加“期望”，根据请求参数返回不同 mock 数据。最重要的是 Apifox 零配置即可 Mock 出非常人性化的数据，具体在本文后面介绍。

数据库操作：支持读取数据库数据，作为接口请求参数使用。支持读取数据库数据，用来校验(断言)接口请求是否成功。

接口自动化测试：提供接口集合测试，可以通过选择接口（或接口用例）快速创建测试集。目前接口自动化测试更多功能还在开发中，敬请期待！目标是：JMeter 有的功能基本都会有，并且要更好用。

快捷调试：类似 Postman 的接口调试方式，主要用途为临时调试一些无需文档化的接口，无需提前定义接口即可快速调试。

代码生成：根据接口及数据数据模型定义，系统自动生成接口请求代码、前端业务代码及后端业务代码。

团队协作：Apifox 天生就是为团队协作而生的，接口云端实时同步更新，成熟的团队/项目/成员权限管理，满足各类企业的需求。

四.Apifox简易使用

4.1 界面概览

接口概览页

接口设计界面

接口运行界面

4.2 接口管理

4.2.1 [接口设计](接口设计 (接口文档) | Apifox 帮助文档)

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

和 Postman 不一样，Apifox 是区分接口设计和接口运行两个概念的。

接口设计：即 新建接口 界面或接口详情里的编辑界面，用途是 定义接口文档规范，而不是运行接口，所以该界面是只能定义接口基本信息、参数名及参数说明等，而不能设置参数值。参数值、前置脚本/后置脚本 等信息请在接口运行界面或接口用例界面填写。
接口运行：即接口详情里的运行界面，用途是 临时调试接口，运行完后，需要点击保存为用例，才能将填写的 参数值、前置脚本/后置脚本 等信息保存下来；否则关闭 tab 后，这些信息将会丢失。
如何像 Postman 那样不用提前设计接口就能快速调试？ 使用 [快捷请求](#4.2.3 快捷请求)。

快速上手

1.点击左侧搜索框旁边的 + 号按钮即可打开新建窗口，也可使用快捷键 Ctrl(⌘) + N。

2.在打开的窗口中，直接定义接口相关信息。

接口路径

以斜杠/起始的接口 path 部分，如/pets、/pets/{id}。

注意

接口路径 建议不要包含 HTTP 协议及域名，这部分建议在环境管理的前置URL里设置，接口调试时的 URL 会自动加上当前环境的前置URL。

特殊情况需在接口路径要带上HTTP 协议及域名的，系统也能支持，但不建议这么做。接口调试时，系统如检测到接口路径是以http://或https://起始的，会自动忽略当前环境里前置 URL。

Apifox 中的 Path 参数是以大括号包裹起来表示，而非冒号起始表示。正确示例：/pets/{id}，*错误示例/pets/:id。*

接口路径 不可包含Query 参数（即 URL 中 ?后的参数），Query 参数在下方请求参数部分填写。

请求参数

Params 参数

包含 Query 参数和 Path 参数两部分。

Query 参数：即 URL 中 ?后的参数。
Path 参数：自动提取接口路径中大括号包裹起来的参数，如/pets/{id}中的的{id}即表示名为id的 Path 参数。

Body 参数

Body 参数类型

none：无 body 参数。
form-data：即 Content-Type 为multipart/form-data。
x-www-form-urlencoded：即 Content-Type 为application/x-www-form-urlencoded。
json：即 Content-Type 为 application/json。
xml：即 Content-Type 为 application/xml。
binary：发送文件类数据时使用。
raw：发送其他文本类数据时使用。

注意

Body 参数类型为json或xml时，需要设置数据结构，并且数据结构可以引用数据模型，详细说明请查看文档：数据结构/数据模型。

接口发送请求的时候会根据Body 参数类型自动在请求Header加上对应的Content-Type，无需手动设置。

若需要手动设置Heade中的Content-Type，则其值必须和Body 参数类型相匹配，否则系统会自动忽略掉手动设置的Content-Type。

示例：如 Body 参数类型为form-data，手动设置Content-Type的值为multipart/form-data; charset=GBK是有效的；但如果把值设置为application/json则会被系统忽略掉，因为和参数类型不匹配。

Body 参数类型为raw时，手动设置Content-Type的值不受限制。

参数中使用环境变量（或全局变量/临时变量）

所有参数都可以使用变量，使用方式为双大括号包裹变量名，如{{my_variable}}，表示引用名为my_variable的变量。

参数值使用变量时可以包含变量以外的字符串，如：参数值设置为prefix-{{my_variable}}-surfix，假设运行时变量my_variable的值为123，则实际请求时参数的值为prefix-123-surfix。

更多关于变量的说明请查看文档：环境变量/全局变量/临时变量。

返回响应

返回响应定义主要包含以下几部分

接口返回的 HTTP 状态码
返回内容的数据格式：JSON、XML、HTML、Raw、Binary
数据结构：仅JSON、XML可配置数据结构，关于数据结构详细说明，请查看文档：数据结构/数据模型

注意

当一个接口在不同情况下会返回不同数据结构时，可设置多个返回响应。点击返回响应模块右上方的+ 新建即可添加。

定义好数据结构后，接口调试时，系统会自动校验返回的数据是否符合定义的数据结构，非常方便，更多说明请查看文档：接口调试/接口用例。

定义好数据结构后，使用 mock 功能时，系统会自动根据定义的数据结构 mock 出非常人性化的数据，非常方便，更多说明请查看文档：Mock 数据

公共响应

公共响应主要用来实现返回响应的复用。

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

设置方法：打开项目设置->公共响应，在这里管理公共响应。

4.2.2 [接口调试](接口调试 / 接口用例 | Apifox 帮助文档)

快速上手

打开接口文档，点击运行 tab 即可。

接口路径、参数名会自动从 修改文档 读取，无需手动输入
参数值默认读取 修改文档 里的 示例值，也可手动修改，进行调试
填写好参数后，点击发送按钮即可运行。

保存为用例

保存为用例 是将当前填写的参数保存起来，方便下次或者其他人用来调试接口。保存为用例后，接口用例 会显示在左侧树状菜单里接口的下一级（如上图）。

注意

接口用例是非常有用的。从团队协作的场景出发，建议每次运行后都保存为用例，后续用接口用例来调试接口是非常高效的。

通常一个接口会有多种情况用例，比如参数正确用例、参数错误用例、数据为空用例、不同数据状态用例等等。

暂存

在已有参数的情况下，修改参数名、数据类型、参数说明，修改项左侧会有“黄色标记”，鼠标移动到“黄色标记”上时，会显示和接口文档的区别。您可以选择复原，和接口文档保持一致；可以选择保存到文档，将修改项同步到接口文档；也可以选择不操作，以当前修改项进行调试。
如果需要新增参数，可以正常添加，添加后整行的左侧会出现“黄色标记”，鼠标移动到“黄色标记”上时，会显示和接口文档的区别。
当修改项很多时，需要整体复原或保存到文档时，可以看到请求参数右上角有不一致文字，鼠标移动上去，根据需要选择。

前置操作/后置操作

前置操作/后置操作 的设置维度支持分组维度、单个接口/接口用例。

分组维度：点击对应的 分组 文件夹即可设置，可自主选择是否对该分组下的接口/接口用例生效。
单个接口/接口用例：可以针对单个接口/接口用例设置 前置操作/后置操作，只对本接口/接口用例生效。
单个接口/接口用例默认继承父级的前/后置操作，可关闭继承；单个接口/接口用例的前/后置操作支持移动到父级分组维度。

断言

后置操作支持添加断言，可对接口返回的数据（或响应时间）设置断言，判断是否符合预期。查看断言功能文档

提取变量

后置操作支持添加提取变量，可从接口返回结果里提取数据，设置到变量（临时变量/环境变量/全局变量），方便其他接口运行的时候直接使用。查看提取变量功能文档

校验响应

校验响应 是一个高效的测试工具，以 接口文档-修改文档 页面内填写的 返回响应 作为判断标准，与 请求接口 的获得的返回值进行对比。

校验响应 的校验范围：

接口返回的 HTTP 状态码
返回内容的数据格式：JSON、XML、HTML、Raw、Binary
数据结构：仅JSON、XML可配置数据结构，关于数据结构详细说明，请查看文档：数据结构/数据模型

如果上述 2 者一致，则显示 ”返回数据结构校验通过!“。说明真实的接口返回值是符合接口文档定义的，不需要人工核对，提高效率和准确性。

当不一致时，就会报错并提示具体是哪部分不一致。此时你可以选择修改 接口文档-修改文档 内的 返回响应 ；也可以通知后端同学修改后端代码。
校验响应 开关默认打开。可以在界面左下角 设置-通用-校验响应 关闭全局开关，注意：全局开关只会对 接口文档-运行 生效，不会对已保存的 接口用例 生效。

4.2.3 [快捷请求](快捷请求 | Apifox 帮助文档)

1.鼠标移到左侧搜索框旁边的 `+` 号按钮，在下拉列表里选择`快捷请求`，也可使用快捷键：Ctrl(⌘) + T。

2.鼠标移动到左侧目录中，在`快捷请求`右边点击 `+` 号按钮，也可新建`快捷请求`

3.输入接口 URL 及参数，即可快速请求接口（如果输入的 URL `不是`以`http://`或`https://`起始，实际发出请求的时候`会`自动加上`当前环境`里前置 URL。）

4.调试完成后，可以保存为`快捷请求`或`接口文档`

5.在左侧目录可以管理已保存的`快捷请求`

6.`快捷请求` 支持 `生成代码`，详情请见生成代码

4.2.4 [数据结构 / 数据模型](数据结构 / 数据模型 | Apifox 帮助文档)

数据结构

数据结构 和编程语言里的数据结构类似，主要使用在接口设计的返回响应和 json / xml 类型的Body 参数。

JSON / XML 智能识别/快捷导入

通过 JSON 数据自动识别生成数据结构，如果你已经有 JSON 数据了，这是一个快捷生成的方式。

注意

JSON 智能识别的作用只是生成数据结构，并不会将 JSON 里的值保存下来。在 2.1.39 版本之后，JSON 智能识别支持识别 注释 字段，并写入说明

快捷导入支持 SQL 建表语句

快捷导入支持 SQL 建表语句，并读取数据库字段长度，写入字段属性。

编辑数据结构

可以选择该字段是否必填

可以选择该字段的数据类型

可以编辑该字段的Mock 设置，具体语法可以查看 Mock 语法
可以新增字段，或删除该字段

可拖拽移动，改变字段之间的排序

数据模型

数据模型是可复用的数据结构。在设计数据结构时可以在数据类型直接选择已经定义好的数据模型。

在使用数据模型前，需要先建立可复用的数据结构。如下图，根据项目需要，可以先在数据模型下新建，也可以简单的管理不同数据模型间的关系。

注意

数据模型之间也可以相互引用

数据模型的引用

在接口设计的返回响应和 json / xml 类型的Body 参数处，在数据类型处可以引用已经建立好的数据模型，如下图。

当前引用的数据模型不符合要求，需要修改时，可以直接跳转到数据模型进行修改

当下接口需要部分引用数据模型时，可以在引用的情况下修改，并且不影响原数据模型
1. 当不需要数据模型中的某个字段时，可以点击隐藏字段，则接口文档中就不会显示了
2. 当需要对数据模型中的某个字段，特殊编辑时，可以点击取消关联。当然后续也可以恢复关联
可以引用多个数据模型，并支持数据模型之间拖拽排序

生成代码

根据数据结构生成各种语言的代码，更多信息请查看文档：代码生成。

4.2.5 [环境管理](环境管理 | Apifox 帮助文档)

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

设置环境

在界面的右上角，是环境管理的入口，可以用过下图两种方式，进入环境管理页面。

环境管理页面

可以在左侧新建或删除环境，右侧可以对某个环境进行编辑。

功能点说明

前置 URL：接口运行时自动添加到接口路径前组成接口实际请求的 URL，如前置 URL 为https://www.api.com，接口路径为/pets/123，那么实际请求的 URL 为https://www.api.com/pets/123。
环境变量：跟随环境切换而发生改变的变量，具体说明可以查看文档环境变量/全局变量/临时变量。
额外参数：当前环境下，给所有接口请求额外加上参数。注：额外参数的参数值可以引用环境变量/全局变量/临时变量。

注意

前置 URL 末尾建议不要加上斜杠/，接口设计时 接口路径 建议以斜杠/起始。

如果接口路径本身就以http://或https://起始，实际发出请求的时候不会自动加上前置 URL。但通常不建议这么使用。

快捷切换环境

根据需要，可以在页面右上角，快速切换为你所需要的环境

服务（前置URL）

注意：正常情况不要添加多个“服务”！！!

当且仅当同一“环境”下，多个接口使用不同的 “前置URL”时，才需要添加多个服务。这种场景下，每个服务设置不同 “前置URL”，不同接口或分组选择不同 “服务”即可。

服务和环境的区别

使用场景示例：

环境：
  开发环境
  测试环境
  预发布环境
  正式环境

服务：
  用户服务（user.xxx.com）：登录等接口
  交易服务（trade.xxx.com）：交易相关接口
  直播服务（live.xxx.com）：直播相关接口

设置服务

在环境管理页面，可以填入所需要的前置 URL。

使用服务

在分组设置中，可以设置当前环境下的不同服务。（推荐使用）

在接口文档-修改文档中，可以设置当前环境下的不同服务。

4.2.6 [环境变量 / 全局变量 / 临时变量](环境变量 / 全局变量 / 临时变量 | Apifox 帮助文档)

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

快速上手

打开环境管理（软件右上角设置形状的按钮），选择全局变量 tab。
添加一个名为my_variable的变量，将本地值设置值为hello，点击保存。
打开一个接口，在运行 tab （或接口用例）的参数值里输入{{my_variable}}即可引用该变量。
点击运行按钮，发送请求，实际运行的时候系统会将{{my_variable}}替换为hello，然后发出请求。

注意

系统内置名为BASE_URL的特殊环境变量，其值为当前环境的前置URL，使用方式{{BASE_URL}}。

如用户手动添加了名为BASE_URL的环境变量，则会覆盖掉系统内置BASE_URL的值。

脚本可通过 pm.environment.get('BASE_URL') 方式读取前置URL。

脚本不能修改前置URL，脚本 pm.environment.set('BASE_URL','xxx')会生成一个真正的名为BASE_URL的环境变量，而不会修改前置URL。

Apifox 版本号大于等于 1.0.12 才支持内置BASE_URL。

本地值和远程值的区别

所有使用到变量的地方，实际运行的时候都是读写本地值，而不会读写远程值。
本地值 仅存放在本地，不会同步到云端，团队成员之间也不会相互同步，适合存放token、账号、密码之类的敏感数据。
远程值 会同步到云端，主要用来团队成员之间共享数据值。

注意

由于本地值仅存放在本地，使用一些清理软件清理 Apifox 文件缓存会导致本地值被清空，请务必注意。

变量类型

环境变量 是最常用的变量，同一个变量可以在不同的环境设置不同的值，变量值会跟随环境切换而改变。环境变量在环境管理模块设置，查看文档：环境管理
全局变量 使用方法类环境变量类似，但全局变量不会跟随环境切换而改变。
临时变量 仅在单次运行接口用例或测试管理里的测试用例或测试套件过程中有效，不会持久化保存。

使用变量

所有类型的变量都是通过双大括号的方式，如{{token}}。
接口运行tab、接口用例、快捷调试、集合测试的所有参数值、前置/后置脚本都可以使用变量。
环境里的额外参数也可以使用变量。

提示

请求 Body 为 json 或者 raw 格式的，也可以直接使用变量、动态变量，使用方式如下：
1
2
3
4
5
6
7
{
    "field1": "{{stringVariable}}",
    "field2": {{intVariable}},
    "field3": {{arrayVariable}},
    "field4": {{objectVariable}},
    "field5": {{$timestamp}}
}
注意：

json 格式里 string 类型的值，使用变量的时候需要加上双引用；其他类型的值不要加双引号，如上面例子所示。

如果以没有加双引号的方式使用了变量，请不要使用格式化功能，如有提示 JSON 格式不正确，直接忽略即可。

若变量的值为对象或数组形式，可以通过{{variableName.attributeName}}或{{variableName[0].attributeName}}方式读取变量里的属性值，示例：

变量user的值为如下格式对象：
1
2
3
4
{
"id": 1,
"name": "jack"
}
1. 接口参数中以{{user.name}}方式引用user对象里的name属性值。
2. 自定义代码中以pm.variables.get("user.name")方式引用user对象里的name属性值。
变量user的值为如下格式数组：
1
2
3
4
5
6
[
{
"id": 1,
"name": "jack"
}
]
1. 接口参数中以{{user[0].name}}方式引用user数组里第一个对象里的name属性值。
2. 自定义代码中以pm.variables.get("user[0].name")方式引用user数组里第一个对象里的name属性值。

如上所示，读取变量（对象或数组）里的属性值写法{{user.name}}遵循JSON Path语法规范，只需将JSON Path里的$符号替换为变量名既可。

变量优先级

所有变量都是通过双大括号的方式引用，当不同类型变量存在相同名称的变量时，系统会根据优先级决定使用哪个类型的变量。

变量优先级：临时变量 > 测试数据变量 > 环境变量 > 全局变量。

脚本中使用变量

环境变量

// 设置环境变量
pm.environment.set('variable_key', 'variable_value');

// 获取环境变量
var variable_key = pm.environment.get('variable_key');

// unset 环境变量
pm.environment.unset('variable_key');

将对象或数组（非字符串）写入环境变量

环境变量写入

环境变量支持数组、对象、字符串等形式存储

var array = [1, 2, 3, 4];
pm.environment.set('array', JSON.stringify(array));

var obj = { a: [1, 2, 3, 4], b: { c: 'val' } };
pm.environment.set('obj', JSON.stringify(obj));

读取的时候，需要使用JSON.parse转换回来

try {
  var array = JSON.parse(pm.environment.get('array'));
  var obj = JSON.parse(pm.environment.get('obj'));
} catch (e) {
  // 处理异常
}

全局变量

// 设置全局变量
pm.globals.set('variable_key', 'variable_value');

// 获取全局变量
var variable_key = pm.globals.get('variable_key');

// unset 全局变量
pm.globals.unset('variable_key');

临时变量

// 设置临时变量
pm.variables.set('variable_key', 'variable_value');

// 获取临时变量
var variable_key = pm.variables.get('variable_key');

// unset 临时变量
pm.variables.unset('variable_key');

4.2.7 [接口修改历史](接口修改历史 | Apifox 帮助文档)

为了更好的支持团队协作的场景，在 2.2.18 之后的版本中，新增 接口修改历史 功能。

接口修改历史 会记录团队成员对接口各个字段的 修改 操作，也会记录因为 导入覆盖 造成的接口文档的修改，并且支持 对比 操作前后的差异，你可以选择 还原 到任意一个历史版本中。

快速上手

当你需要查看 接口修改历史 时，点击 接口文档 内的右上角的 icon，即可展开 接口修改历史。

点击某一条记录，则可以显示这次操作前后，各个字段变化的情况

如果需要恢复到上一个版本，可以点击 还原此版本，则会将使用这个的历史版本内容生成一个新版本，原本的修改历史不受影响。

4.3 全自动登录实现

1.运行接口用例的时候，自动完成登录，而无需手动登录。
2.自动登录过一次后，保存登录态，避免每次执行用例都调用登录接口。

实现思路

使用环境变量（如：ACCESS_TOKEN）保存登录需要的凭证。
如凭证有过期时间，使用环境变量（如：ACCESS_TOKEN_EXPIRES）保存登录凭证的过期时间。
创建一个公共脚本：
1. 判断环境变量ACCESS_TOKEN是否有值，以及ACCESS_TOKEN_EXPIRES是否过期，如果存在且未过期，跳出执行，否则下一步。
2. 使用 pm.sendRequest 调用登录接口，将登录接口返回的登录凭证写入环境变量，过期时间也写入环境变量。
设置需要登录态的接口用例：
1. 将用来验证登录态的参数值设置为{{ACCESS_TOKEN}} 。
  - 将 header 里的Authorization的设置为{{ACCESS_TOKEN}}。注意：这里也可以使用 Cookie 或其他位置的参数，请根据实际情况确定。
  - 此处也可以在环境里的 全局参数 统一设置，所有接口运行时会自动加上 全局参数，无需每个接口手动设置。
2. 在 前置脚本 里引用前面创建公共脚本。

示例（以lsh-plat为例）

公共脚本

新建 全自动登录实现公共脚本

脚本内容

// 定义发送登录接口请求方法
function sendLoginRequest() {
  // 获取环境里的 前置URL
  const baseUrl = pm.environment.get("BASE_URL");

  // 登录用户名，这里从环境变量 LOGIN_USERNAME 获取，也可以写死（但是不建议）
  const username = pm.environment.get("LOGIN_USERNAME");

  // 登录密码，这里从环境变量 LOGIN_PASSWORD 获取，也可以写死（但是不建议）
  const password = pm.environment.get("LOGIN_PASSWORD");

  // 构造一个 POST  格式请求。这里需要改成你们实际登录接口的请求参数。
  const loginRequest = {
    url: baseUrl + "/auth/login",
    method: "POST",
    header: {
      "Content-Type": "application/json", // 注意：header 需要加上Content-Type
    },
    body: {
      mode: 'raw',// 此处为 raw
      raw: JSON.stringify({ "userNo": username, "userPwd":password }), // 序列化后的 json 字符串
    }
  };

  // 发送请求。
  // pm.sendrequest 参考文档: https://www.apifox.cn/help/app/scripts/api-references/pm-reference/#pm-sendrequest
  pm.sendRequest(loginRequest, function(err, res) {
    if (err) {
      console.log(err);
    } else {
      // 读取接口返回的 json 数据。
      // 如果你的 token 信息是存放在 cookie 的，可以使用 res.cookies.get('token') 方式获取。
      // cookies 参考文档：https://www.apifox.cn/help/app/scripts/api-references/pm-reference/#pm-cookies
      const jsonData = res.json();
      // 将 accessToken 写入环境变量 ACCESS_TOKEN
      pm.environment.set("ACCESS_TOKEN", jsonData.result.token);
      // 将 accessTokenExpires 过期时间写入环境变量 ACCESS_TOKEN_EXPIRES
      pm.environment.set(
        "ACCESS_TOKEN_EXPIRES",
        jsonData.result.tokenExpires
      );
    }
  });
}

// 获取环境变量里的 ACCESS_TOKEN
const accessToken = pm.environment.get("ACCESS_TOKEN");

// 获取环境变量里的 ACCESS_TOKEN_EXPIRES
const accessTokenExpires = pm.environment.get("ACCESS_TOKEN_EXPIRES");

// 如 ACCESS_TOKEN 没有值，或 ACCESS_TOKEN_EXPIRES 已过期，则执行发送登录接口请求
if (
  !accessToken ||
  (accessTokenExpires && new Date(accessTokenExpires) <= new Date())
) {
  sendLoginRequest();
}

根目录前置操作

选择 全自动登录实现公共脚本

全局参数

环境变量

4.4 自动化测试

4.4.1 [测试用例](测试用例 | Apifox 帮助文档)

测试用例是将多个接口有序地组合在一起运行，用来测试一个完整业务流程。

新建测试用例

路径：自动化测试-测试用例

点击新建测试用例，根据需要新建一个测试用例。

添加测试步骤

选中某个测试用例，进入编辑页面。

在测试用例的编辑页面，把鼠标移动到添加步骤上，会展示菜单。

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

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

注意

从接口导入后，需要手动设置接口参数，否则运行的时候，接口参数是空的。

从接口用例导入后，会同步导入接口用例里的参数，会方便很多。

从接口用例导入例图

从接口导入例图

导入成功后，一定要记得点击保存哦。

注意

导入的 接口 或 接口用例 在测试用例中作为一个 测试步骤 。测试步骤 是引用了 接口 或 接口用例，

复制 测试步骤，是复制一个已经设置了绑定模式的 测试步骤

运行测试用例

点击运行，则进入自动化测试。

测试报告

运行完成后，如图所示，可以看到哪些接口没有通过测试，可以点击对应的接口展开详情；点击更多详情，可以查看该接口的运行结果，方便定位问题。

运行结束后可以从下面两个入口，查看之前的测试报告，也可以导出。

测试数据

点击这里查看[测试数据](#4.4.2 测试数据)

常见问题

B 接口请求参数依赖于 A 接口返回的数据，如何实现？

使用后置脚本和变量（普通变量、环境变量或全局变量）。

A 接口的用例里编写后置脚本，将接口请求返回的数据写入变量，示例：

// 获取 JSON 格式的请求返回数据
var jsonData = pm.response.json();

// 将 jsonData.token 的值写入变量
pm.variables.set("token", jsonData.token);

B 接口对应的参数值，设置为对应的变量，如{{token}}，即可直接引用前面设置的变量token的值。

4.4.2 [测试数据](测试数据 | Apifox 帮助文档)

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

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

编辑测试数据

打开测试用例或测试套件详情页就可以看到测试数据页。通过添加数据集、批量编辑、添加变量等直接编辑测试数据；点击导入可以导入本地csv文件的数据。

使用测试数据

测试步骤导入的接口或用例，通过引用变量的方式获取测试数据。

运行测试数据

在运行前需要打开测试数据的开关，再点击运行

常见问题

1. 中文导入后乱码的问题

是因为 windows 默认导出 csv 是 GBK，并且旧版本的 Excel 2016 前会不保存 Bom (byte order mark)。

Windows 可以使用记事本打开 csv 文件后另存为 utf-8 格式。
Mac 上可以使用 iconv -f GBK -t UTF-8 xxx.csv > utf-8.csv。

4.4.3 性能测试

性能测试有 3 种方式。

一、Apifox 应用内测试

运行测试用例的时候，设置线程数大于1即可实现性能测试。

线程数即同时【并发】运行的线程数，每个线程都会按顺序运行选中的所有步骤。

注意

该功能为 beta 阶段，还在优化中，高并发测试建议导出 JMeter 文件的方式来测试。

二、Apifox CLI 方式测试

Apifox CLI 是 Apifox 的命令行运行工具，主要用来做持续集成和压力测试，其压力测试功能目前正在开发中，敬请期待！

三、导出 JMeter 测试

测试用例和测试套件可以导出JMeter格式数据，然后可以导入 JMeter 做性能测试。

4.4.4 测试流程控制

借助测试流程控制，开发者可以在测试步骤中新增流程控制条件（循环、判断、等待、分组）等。进一步满足了更复杂的测试场景/流程配置的使用，最终借助自动化测试功能解决复杂场景的测试工作。

循环

当测试步骤需要重复执行时，可以通过设置循环次数来解决。同时，循环的附加设置中，支持自定义设置 中断条件/遇到错误时 判断。

示例：宠物店店主在结束营业的晚上，登录宠物库存管理后台，将今日出售的10个宠物，分别进行详情查看并将它的在售状态变为已售出。

点击底部的按钮「添加步骤」，并选择「循环」。
输入需要的循环次数 10 。

将该测试步骤拖入该条件下内框中（你也可在该条件下直接添加测试步骤）。

判断

当测试流程中存在多条件判断时，可以通过添加判断条件（ If ）来区分流程执行的步骤。即当判断配置的条件满足时，该判断条件下的子步骤才会执行, 相反子步骤则会被跳过。

示例：宠物店店主根据昨日宠物出售情况，若判断为售出，将该宠物的出售状态设置为“已售出”。否则( else )，查询在售中列表。

点击底部的按钮「添加步骤」，并选择「条件分支」。
在lf条件后面的输入框填写请求接口得到的变量 saleStatus ，然后选择条件”等于”，最后输入比较数值为 true。(当销售状态判断为 true 的时候，则更改宠物信息为「已售出」)
将鼠标悬浮在该条件分支操作拦会出现「＋ Else 」，点击并新增「出售中的宠物列表」步骤（否则，即查询在售中的宠物列表。）。
将测试步骤拖入到相应的条件分支中。

等待

当测试流程中某个步骤需要执行后需要等待一段时间时，比如 A 步骤需要等待若干时间后再执行 B 步骤，可以通过新增等待条件来解决。

示例：模拟用户查看宠物详情，浏览 1000ms 后，将该宠物详情信息中的浏览状态进行更新。

点击底部的按钮「添加步骤」，并选择「等待」。
点击底部的按钮「添加步骤」，并选择「等待」。

分组

当测试流程中多个步骤存在相关联关系时，可以进行归类并放入到同一个分组中。通过对测试步骤的分组，让测试用例具备更好的可读性和操作性。

示例：将查看详情宠物详情、修改宠物信息、再次查看详情等步骤归类成分组。

点击底部的按钮「添加步骤」，并选择「分组」。
将要归类的步骤，拖到分组步骤下或在分组中直接添加步骤。

4.5 导入\导出

4.5.1 导入数据

支持导入 OpenApi (原Swagger)、Postman、HAR、RAML、RAP2、JMeter、YApi、Eolinker、NEI、DOClever、ApiPost 、Apizza 、DOCWAY、ShowDoc、apiDoc、I/O Docs、WADL、Google Discovery等数据格式，方便旧项目迁移。

快速上手

手动导入

打开 项目设置 面板，点击 手动导入 ，可选择文件导入或 URL 导入。

以导入 Apifox 格式为例，导入可选内容包括：接口、数据模型、环境、测试用例、测试套件

注意

导入 OpenAPI/Swagger 格式只包含 接口、数据模型、环境

导入 Postman 格式只包含 接口

手动导入-高级设置

匹配相同接口时

覆盖所有字段：当两个接口的接口唯一标识相同时，新文件会覆盖旧文件
不导入：当两个接口的接口唯一标识相同时，新文件不会导入
保留两者：当两个接口的接口唯一标识相同时，新文件会导入，旧文件不会被删除

匹配相同文档时

覆盖：当两个文档名称相同时，新文件会覆盖旧文件
不导入：当两个文档名称相同时，新文件不会导入
保留两者：当两个文档名称相同时，新文件会导入，旧文件不会被删除

导入到目录

支持将文件导入到具体的目录中

导入接口用例

开启开关后，已选择接口下的接口用例默认全选，也可以在 导入预览 中选择对应 接口用例

当导入非 Apifox 格式文件，且接口文档覆盖时，名称相同的 接口用例 不会导入，不同名称的 接口用例 会新增。
当导入 Apifox 格式文件，且接口文档覆盖时，名称相同的 接口用例 会覆盖，不同名称的 接口用例 会新增。

自动导入

打开项目设置面板，点击自动导入，可设置多个数据源，定时同步到具体分组中

注意

只有角色为管理员，且打开客户端的时候，才会按照设置的导入频率 自动导入 。

其他角色不会触发自动导入 。

主界面快速导入

在 2.2.27 版本之后，支持在主界面（项目列表页）快速导入数据。可以选择导入到新项目，或导入到已有项目。

导入不同数据源

导入数据 | Apifox 帮助文档

4.5.2 导出数据

支持直接导出 OpenAPI (原Swagger)、HTML、Markdown、Apifox等数据格式。
OpenAPI (Swagger) 支持导出 3.1、3.0、2.0 版本。
OpenAPI (Swagger) 支持导出离线文件，或直接打开 URL。

导出 PDF 方法

目前还不支持直接导出 PDF、Word 等其他格式数据，但可使用外部工具将Markdown转为对应格式。

如使用 Mdnice 即可将 Markdown 导出为 PDF格式。

常见问题

导出 Markdown、HTML 格式时接口顺序为什么乱了？

Swagger 规范里是没有顺序的概念的，也没有分组的概念，规范本身不支持，所以导出 Swagger 格式是错乱的。

html 和 markdown 都是用 swagger 转制的，同样存在问题。

如果需要顺序的话，建议选择 apifox 格式导出

多个同 URL 接口，导出后只有一个？ 导出的接口数量为什么变少了？

请检查是否有多个接口都是使用相同的方法和路径。

OpenAPI 规范是不支持不同接口使用相同方法和路径的。如存在多个接口使用相同方法和路径的情况，请查看接口唯一标识

目前导出HTML、Markdown是通过 OpenAPI 数据转译的。同样存在问题。

快速上手

打开项目设置面板，点击导出即可使用导出数据功能。

支持导出全部，也可以导出部分接口，如图，可以根据需要选择对应的接口，并支持搜索与筛选。

支持根据标签来导出对应的接口

4.6 生成代码

功能说明

根据接口模型定义，自动生成各种语言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等 130 种语言及框架）的业务代码（如 Model、Controller、单元测试代码等）和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。

更重要的是：你可以通过自定义代码模板来生成符合自己团队的架构规范的代码，满足各种个性化的需求。

接口文档的代码生成

可以在接口文档-文档页，接口文档-运行页、接口用例，根据需要选择 生成接口请求代码、生成完整项目代码。

接口文档-文档页

接口文档-运行页

接口用例

数据模型的代码生成

数据模型的生成 SQL 建表语句

4.7 分享 & 发布文档

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

分享在线文档

在软件界面左侧，就可以设置当前项目的在线文档

点击新建分享，就可以根据需要，设置分享的信息内容：

文档语言
访问密码
分享在线文档的日期
分享范围：可以选择项目全部，也可以选择部分接口，也可以根据标签维度导入
运行环境：可以选择运行的环境，和显示对应的前置 URL。选择后，分享出去的在线接口文档支持运行调试
可以显示接口文档对应的责任人、修改时间、前置 URL

整目录分享

在线文档支持整目录分享功能，选择对应的分组打开整目录分享，则该分组在修改后会自动同步到在线文档。当然如果您不希望在线文档实时同步您的修改，可以选择不开启。

设置完成后，复制链接，就可以分享给团队成员了

查看在线文档

在线文档查看过程中，支持复制接口 URL、数据接口字段、返回示例字段

在线文档支持修改环境变量

前提条件：当设置 在线分享 时，需要设置接口引用了 环境变量 的环境

在线文档调试接口时，会存在修改接口文档引用的 环境变量 的场景，现在可以根据下图，修改 环境变量 并运行调试

在线文档支持显示示例代码

分享出去的 在线接口文档 支持显示示例代码，当然 API Hub 也是支持的。您可以直接复制当前接口的代码，直接使用。

参考文档

帮助中心 | Apifox 帮助文档

Apifox IDEA 插件快速上手 | Apifox 帮助文档

开发工具：让前后端联调不再争吵——Apifox_apifox前后端联调_ABin-阿斌的博客-CSDN博客

Apifox快速上手

前言

团队原来的工作模式

存在的问题

如何解决

最佳实践

一.安装运行Apifox

1.1安装

1.2扫码注册登录

1.3加入团队

1.4完成

二.IDEA插件安装使用

2.1 介绍

2.2 功能特性

2.3 安装

从 IDEA plugins 中搜索安装

2.4 获取项目ID

2.5获取访问令牌

2.6基础配置

2.7同步接口到 Apifox

同步模块内所有接口

同步 controller 文件内所有接口

同步选择部分接口

三.Apifox介绍

3.1 Apifox 定位

Apifox = Postman + Swagger + Mock + JMeter

3.2 Apifox 宗旨

3.3 Apifox 功能

四.Apifox简易使用

4.1 界面概览

接口概览页

接口设计界面

接口运行界面

4.2 接口管理

4.2.1 [接口设计](接口设计 (接口文档) | Apifox 帮助文档)

快速上手

接口路径

请求参数

Params 参数

Body 参数

参数中使用环境变量（或全局变量/临时变量）

返回响应

公共响应

4.2.2 [接口调试](接口调试 / 接口用例 | Apifox 帮助文档)

快速上手

保存为用例

暂存

前置操作/后置操作

断言

提取变量

校验响应

4.2.3 [快捷请求](快捷请求 | Apifox 帮助文档)

1.鼠标移到左侧搜索框旁边的 + 号按钮，在下拉列表里选择快捷请求，也可使用 快捷键：Ctrl(⌘) + T。

2.鼠标移动到左侧目录中，在快捷请求右边点击 + 号按钮，也可新建快捷请求

3.输入接口 URL 及参数，即可快速请求接口（如果输入的 URL 不是以http://或https://起始，实际发出请求的时候会自动加上当前环境里前置 URL。）

4.调试完成后，可以保存为快捷请求或接口文档

5.在左侧目录可以管理已保存的快捷请求

6.快捷请求 支持 生成代码，详情请见 生成代码

4.2.4 [数据结构 / 数据模型](数据结构 / 数据模型 | Apifox 帮助文档)

数据结构

编辑数据结构

数据模型

数据模型的引用

生成代码

4.2.5 [环境管理](环境管理 | Apifox 帮助文档)

设置环境

服务（前置URL）

4.2.6 [环境变量 / 全局变量 / 临时变量](环境变量 / 全局变量 / 临时变量 | Apifox 帮助文档)

快速上手

本地值和远程值的区别

变量类型

使用变量

变量优先级

脚本中使用变量

环境变量

全局变量

临时变量

4.2.7 [接口修改历史](接口修改历史 | Apifox 帮助文档)

快速上手

4.3 全自动登录实现

1.鼠标移到左侧搜索框旁边的 `+` 号按钮，在下拉列表里选择`快捷请求`，也可使用快捷键：Ctrl(⌘) + T。

2.鼠标移动到左侧目录中，在`快捷请求`右边点击 `+` 号按钮，也可新建`快捷请求`

3.输入接口 URL 及参数，即可快速请求接口（如果输入的 URL `不是`以`http://`或`https://`起始，实际发出请求的时候`会`自动加上`当前环境`里前置 URL。）

4.调试完成后，可以保存为`快捷请求`或`接口文档`

5.在左侧目录可以管理已保存的`快捷请求`

6.`快捷请求` 支持 `生成代码`，详情请见生成代码