导入/导出

导入数据

功能说明

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

快速上手

手动导入

打开项目设置面板，点击手动导入，可选择文件导入或 URL 导入。
image.png
以导入 Apifox 格式为例，导入可选内容包括：接口、数据模型、环境、测试用例、测试套件

注意

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

image.png

手动导入-高级设置

  1. 接口覆盖模式image.png
    1. 同 URL 覆盖：当两个文件 URL、method 相同时，新文件会覆盖旧文件
    2. 同 URL 且同分组才覆盖：当两个文件的 URL、method 相同时，并且在同一个分组下时，新文件会覆盖旧文件
    3. 同 URL 不导入：当两个文件 URL、method 相同时，新文件不会导入
    4. 同 URL 时保留两者：当两个文件 URL、method 相同时，新文件会导入，旧文件不会被删除
  2. 文件（markdown 文档、数据模型、测试用例、接口用例）覆盖模式
    1. 同名覆盖：当两个文件名称相同时，新文件会覆盖旧文件
    2. 同名且同分组才覆盖：当两个文件的名称相同时，并且在同一个分组下时，新文件会覆盖旧文件
    3. 同名不导入：当两个文件名称相同时，新文件不会导入
    4. 同名时保留两者：当两个文件名称相同时，新文件会导入，旧文件不会被删除
  3. 导入到分组：支持将文件导入到具体的分组中image.png
  4. 导入接口用例：开启开关后，已选择接口下的接口用例默认全选，也可以在 导入预览 中选择对应 接口用例tip：当接口文档覆盖时，名称相同的接口用例，新文件会覆盖旧文件；名称不同的接口用例会导入；名称不同的旧有接口用例会保留image.png

    自动导入

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

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

image.png image.png

导入不同的数据源

一、导入 OpenAPI (Swagger) 数据

支持导入 OpenAPI 3、Swagger 1、2、3数据格式的json或yaml文件。

注意 需要URL导入的时候，需要填写的是json或yaml数据文件的 URL，而不是Swagger UI的 URL。 image.png

二、导入 Postman 数据

支持 Postman Collection v2.1 格式。
数据导出方法：找到 Postman 左侧列表 Collections，鼠标移到需要导出的集合，点击···，选择Export然后选择Collection v2.1 (recommended)即可导出，如下图所示：
image.png

三、导入 ShowDoc 格式数据

数据导出方法：点击 ShowDoc 文档右侧的展开按钮，找到导出按钮，点击后选择 markdown 压缩包 导出。
image.png
将从 ShowDoc 导出的 Markdown 压缩包 解压，会看到一个文件名为prefix_info.json的 json 文件。
导入 Apifox 的时候，选择ShowDoc格式，然后导入前面解压得到的prefix_info.json文件即可。

四、导入 Eolinker 数据

支持Eolinker 项目数据 (.json)格式。
Eolinker 数据导出方法：打开 Eolinker 里对应项目，点击左侧菜单项目设置，在项目 Tab 里点击导出项目，选择Eolinker 项目数据 (.json)，然后导出，如下图所示：
image.png
image.png

五、导入 ApiPost 数据

支持 ApiPost Markdown 格式数据格式.
数据导出方法：Apipost 版本 ≥5.4.2，打开 ApiPost，点击左侧导航项目，选择对应项目，点击右侧分享项目文档，在浏览器打开分享链接，在打开的网页里，找到右上角导出文档，选择导出MarkDown，然后导出，如下图所示：
image.png
image.png
image.png

六、导入 DOCWAY 数据

支持 DOCWAY 复制分享地址的方式导入数据。
使用方法：打开 DOCWAY，进入对应项目，鼠标移到左上角更多功能点击分享项目（注意仅项目创建者有权限分享项目），创建分享 (注意“阅读密码”必须设置为空)，然后复制分享地址将地址黏贴到下面输入框。如下图所示：
image.png
image.png
image.png
image.png

七、导入 NEI 数据

支持 NEI json 格式数据导入。
NEI 导出数据方法：https://github.com/NEIAPI/nei/issues/27

八、导入 Knife4j 数据

支持 Knife4j 导出 OpenAPI 格式导入。
导出方法：打开 Knife4j （>=2.0.6 版本），在文档管理 => 离线文档菜单栏中，选择 OpenAPI导出。
image.png

导入的数据源

导入 OpenAPI (Swagger) 数据

支持导入 OpenAPI 3、Swagger 1、2、3 数据格式的 json 或 yaml 文件。

手动导入

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

手动导入-文件导入

可以将 json 或 yaml 文件拖拽到下图区域，也可以点击下图区域通过系统的文件管理器选择对应的 json 或 yaml 文件。
image.png

手动导入-URL 导入

注意 需要 URL 导入的时候，需要填写的是 json 或 yaml 数据文件的 URL，而不是 Swagger UI 的 URL。 image.png

image.png

导入-高级设置

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

  1. 接口覆盖模式image.png
    1. 同 URL 覆盖：当两个文件 URL、method 相同时，新文件会覆盖旧文件。
    2. 同 URL 且同分组才覆盖：当两个文件的 URL、method 相同时，并且在同一个分组下时，新文件会覆盖旧文件。
    3. 同 URL 不导入：当两个文件 URL、method 相同时，新文件不会导入。
    4. 同 URL 时保留两者：当两个文件 URL、method 相同时，新文件会导入，旧文件不会被删除。
  2. 导入到分组：支持将文件导入到具体的分组中。image.png
  3. 导入接口用例：开启开关后，已选择接口下的 接口用例 默认全选，也可以在 导入预览 中选择对应 接口用例 。tip：当接口文档覆盖时，名称相同的 接口用例 ，新文件会覆盖旧文件；名称不同的 接口用例 会导入；名称不同的旧有 接口用例 会保留。image.png
  4. 数据模型需要独立设置 选择覆盖模式 和 导入到分组 的，如图image.png

    自动导入

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

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

image.png image.png

注意 需要 URL 导入的时候，需要填写的是 json 或 yaml 数据文件的 URL，而不是 Swagger UI 的 URL。 image.png

导入抓包数据 (cURL)

快速导入 Chome、Charles 或 Fiddler 等工具的抓包数据。

快速上手

  1. 使用 Chome、Charles 或 Fiddler 等工具抓包，然后复制为cURL格式。image.pngimage.png
    • Chrome 使用方式：打开 Chrome 开发中工具，抓包，找到对应接口请求，单击右键->Copy->Copy as cURL，如下图所示。
    • Charles 使用方式：抓包，找到对应接口，单击右键->Copy cURL Request，如下图所示。
    • Fiddler 使用方式：抓包，点击左上角菜单 File->Export Sessions->Selected Sessions，选项第一个默认 cURL script，点击Next即可保存为.bat文件，文件编辑工具打开该.bat ，复制内容即可。查看详细使用说明
  2. 鼠标移到左侧搜索框旁边的 + 号按钮，在下拉列表里点击导入抓包数据，也可使用 快捷键 Ctrl(⌘) + I。image.png
  3. 在打开的窗口中，粘贴从前面抓包数据里复制的 cURL 格式数据。image.png
  4. 点击确定按钮，即可看到抓包的数据已复制到如下快捷调试界面。image.png
  5. 快捷调试窗口可以直接调试接口，点击保存按钮，可以保存为接口。

    导出数据

    功能说明

    支持直接导出 OpenAPI (原Swagger)、HTML、Markdown 等数据格式。
    image.png

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

常见问题

  • 导出的接口数量为什么变少了？ 请检查是否有多个接口都是使用相同的方法和路径，目前导出HTML、Markdown是通过 OpenAPI 数据转换的，而 OpenAPI 规范是不支持不同接口使用相同方法和路径的。
  • 导出 Markdown、HTML 格式时接口顺序为什么乱了？
  1. Swagger 规范里是没有顺序的概念的，也没有分组的概念，规范本身不支持，所以导出 Swagger 格式是错乱的。
  2. html 和 markdown 都是用 swagger 转制的，同样存在问题。
  3. 如果需要顺序的话，建议选择 apifox 格式导出
  • 多个同 URL 接口，导出后只有一个？
  1. Swagger 规范本身不支持
  2. html 和 markdown 都是用 swagger 转制的，同样存在问题。

快速上手

打开项目设置面板，点击导出即可使用导出数据功能。
支持导出全部，也可以导出部分接口，如图，可以根据需要选择对应的接口
image.png image.png
支持根据标签来导出对应的接口
image.png

在线文档

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

分享在线文档

在软件界面左侧，就可以设置当前项目的在线文档
image.png image.png
点击新建分享，就可以根据需要，设置分享的信息内容：

  1. 访问密码
  2. 分享在线文档的日期

  3. 分享范围：可以选择项目全部，也可以选择部分接口，也可以根据标签维度导入

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

  4. 可以选择运行的环境，和显示对应的前置 URL

  5. 可以显示接口文档对应的责任人、修改时间

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

查看在线文档

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

代码生成

功能说明

根据接口模型定义，自动生成各种语言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等 130 种语言及框架）的业务代码（如 Model、Controller、单元测试代码等）和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。
更重要的是：你可以通过自定义代码模板来生成符合自己团队的架构规范的代码，满足各种个性化的需求。

安装插件

打开生成代码面板，点击安装插件即可自动下载并安装。

安装 Java 环境

运行代码生成插件需要 Java 环境。请查看 安装 Java 环境。

接口管理

接口设计 (接口文档)

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

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

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

新人常见问题

  • 如何像 Postman 那样不用提前设计接口就能快速调试？ 使用 快捷请求 功能。
  • 如何固定 tab，避免新打开接口的时候覆盖掉已打开的 tab？ 双击 tab 头或者双击树形菜单的对应内容，用法和 VS Code完全一样。（修改tab里的内容后，会自动固定 tab）

快速上手

  1. 点击左侧搜索框旁边的 + 号按钮即可打开新建窗口，也可使用 快捷键 Ctrl(⌘) + N。image.png
  2. 在打开的窗口中，直接定义接口相关信息。image.png

    接口路径

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

    注意

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

基础信息

这部分比较简单，一看就懂，不再赘述。

请求参数

Params 参数

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

  • Query 参数：即 URL 中 ?后的参数。

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

    Body 参数

    image.png
    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：发送其他文本类数据时使用。

    注意

    • GET方式的接口，body 参数只能设置为none。
    • Body 参数类型为json或xml时，需要设置数据结构，并且数据结构可以引用数据模型，详细说明请查看文档：数据结构/数据模型。

注意

  • 接口发送请求的时候会根据Body 参数类型自动在请求Header加上对应的Content-Type，无需手动设置。
  • 若需要手动设置Header中的Content-Type，则其值必须和Body 参数类型相匹配，否则系统会自动忽略掉手动设置的Content-Type。
    1. 示例：如 Body 参数类型为form-data，手动设置Content-Type的值为multipart/form-data; charset=GBK是有效的；但如果把值设置为application/json则会被系统忽略掉，因为和参数类型不匹配。
    2. Body 参数类型为raw时，手动设置Content-Type的值不受限制。

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

所有参数都可以使用变量，使用方式为双大括号包裹变量名，如{{my_variable}}，表示引用名为my_variable的变量。
参数值使用变量时可以包含变量以外的字符串，如：参数值设置为prefix-{{my_variable}}-surfix，假设运行时变量my_variable的值为123，则实际请求时参数的值为prefix-123-surfix。
更多关于变量的说明请查看文档：环境变量/全局变量/临时变量。

返回响应

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

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

    注意

    • 当一个接口在不同情况下会返回不同数据结构时，可设置多个返回响应。点击返回响应模块右上方的+ 新建即可添加。
    • 定义好数据结构后，接口调试时，系统会自动校验返回的数据是否符合定义的数据结构，非常方便，更多说明请查看文档：接口调试/接口用例。
    • 定义好数据结构后，使用 mock 功能时，系统会自动根据定义的数据结构 mock 出非常人性化的数据，非常方便，更多说明请查看文档：Mock 数据

全局响应

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

响应示例

image.png
设置返回 Response 的示例数据，方便查阅接口文档的人快速了解数据结构。
返回 Response 的示例数据也可以设置多次，点击响应示例模块右上方的+ 新建即可添加。建议至少设置两个示例：成功示例、失败示例。

其他

OperationID

支持设置 OperationId属性，导出OpenAPI格式时会将此处的值导出到 Operation 对象的 OperationId 里
image.png

接口调试 / 接口用例

设计好接口文档后，就可以直接运行接口来调试了。

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

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

新人常见问题

  • 如何像 Postman 那样不用提前设计接口就能快速调试？ 使用 快捷调试 功能。
  • 如何固定 tab，避免新打开接口的时候覆盖掉已打开的 tab？ 双击 tab 头或者双击树形菜单的对应内容，用法和 VS Code完全一样。（修改tab里的内容后，会自动固定 tab）

快速上手

打开接口详细，点击运行 tab 即可。
image.png

接口参数

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

保存为用例

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

注意

  • 接口用例是非常有用的，建议每次运行后都保存为用例，后续用接口用例来调试接口是非常高效的。
  • 通常一个接口会有多种情况用例，比如参数正确用例、参数错误用例、数据为空用例、不同数据状态用例等等。

返回响应

返回响应是用来给系统校验接口请求后返回的数据是否符合对应 Response 里定义的数据结构，免去人眼识别，提高效率和准确性。

数据结构校验结果

系统会根据选择的返回响应的数据结构，自动分析运行后返回的数据是否正确，并且给出详细的错误提示。

断言

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

提取变量

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

控制台

控制台主要用来展示，脚本里输出的调试信息，以及脚本运行时的错误信息，方便进行脚本调试。

前置操作/后置操作

断言

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

示例

设置断言：
image.png
运行后，查看断言结果：
image.png

提取变量

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

示例

image.png

数据库操作

前置操作、后置操作支持添加数据库操作，可读写数据库数据，查询结果可在接口请求参数、断言、自定义脚本等场景中使用。目前支持MySQL、SQL Server、Oracle、PostgreSQL，未来会支持更多数据库类型。

示例

  1. 在前置操作里添加数据库操作
  2. SQL 为 SELECT * FROM user LIMIT 2。
  3. 将查询结果提取到 3 个变量：allUser，user，userName。

image.png

说明

假设 SQL 查询结果数据为：

  1. [
  2.   {
  3.     "id": 1,
  4.     "name": "jack"
  5.   },
  6.   {
  7.     "id": 2,
  8.     "name": "peter"
  9.   }
  10. ]

则提取到的变量值分别为如下：

  1. 临时变量allUser的值是数组类型，值为：

    1. [
    2. {
    3.  "id": 1,
    4.  "name": "jack"
    5. },
    6. {
    7.  "id": 2,
    8.  "name": "peter"
    9. }
    10. ]

  2. 临时变量user的值是对象类型，值为：

    1. {
    2. "id": 1,
    3. "name": "jack",
    4. "sex": "male"
    5. }

  3. 临时变量userName的值是字符串类型，值为：

    jack

    变量使用提示

    使用变量时，读取对象或数组类型变量里的属性值写法为{{allUser[0].name}}或{{user.name}}，遵循JSON Path语法规范，只需将JSON Path里的$符号替换为变量名既可。
    更多变量使用方法请查看文档。

    数据结构 / 数据模型

    数据结构

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

    JSON 智能识别/快捷导入

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

    注意 JSON 智能识别的作用只是生成数据结构，并不会将 JSON 里的值保存下来。

image.png image.png

编辑数据结构

  1. 可以选择该字段是否必填

image.png

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

image.png

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

image.png

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

image.png

  1. 关于填写说明的高效率的方式，我们正在开发中，敬请期待。

    数据模型

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

    管理数据模型

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

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

数据模型的引用

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

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

image.png

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

image.png image.png

预览

根据设计的数据结构，mock 出假数据，方便查看数据结构的实际效果。

生成代码

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

编辑源码

Apifox 的数据结构和数据模型是完全遵守 JSON Schema 规范 的，所以可以直接编辑 JSON Schema 的方式来定义数据结构。参考文档：JSON Schema 介绍

快捷请求

使用场景

临时需要调试某个接口，而不需要保存为文档或者用例。

快速上手

  1. 鼠标移到左侧搜索框旁边的 + 号按钮，在下拉列表里选择快捷请求，也可使用 快捷键：Ctrl(⌘) + T。image.png
  2. 鼠标移动到左侧目录中，在快捷请求右边点击 + 号按钮，也可新建快捷请求image.png

  3. 输入接口 URL 及参数，即可快速请求接口image.png

    注意 如果输入的 URL 不是以http://或https://起始，实际发出请求的时候会自动加上当前环境里前置 URL。

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

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

    环境管理

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

    设置环境

    环境管理的入口

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

    环境管理页面

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

    功能点说明

  6. 前置 URL：接口运行时自动添加到接口路径前组成接口实际请求的 URL，如前置 URL 为https://www.api.com，接口路径为/pets/123，那么实际请求的 URL 为https://www.api.com/pets/123。

  7. 环境变量：跟随环境切换而发生改变的变量，具体说明可以查看文档 环境变量/全局变量/临时变量。
  8. 额外参数：当前环境下，给所有接口请求额外加上参数。注：额外参数的参数值可以引用环境变量/全局变量/临时变量。

    注意

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

注意

  • 系统内置名为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。

快捷切换环境

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

服务（前置URL）

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

服务和环境的区别

使用场景示例：

环境： 开发环境 测试环境 预发布环境 正式环境 服务： 用户服务（user.xxx.com）：登录等接口 交易服务（trade.xxx.com）：交易相关接口 直播服务（live.xxx.com）：直播相关接口

设置服务

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

使用服务

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

image.png

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

image.png

环境变量使用

查看文档

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

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

快速上手

  1. 打开环境管理（软件右上角设置形状的按钮），选择全局变量 tab。image.pngimage.png
  2. 添加一个名为my_variable的变量，将本地值设置值为hello，点击保存。
  3. 打开一个接口，在运行 tab （或接口用例）的参数值里输入{{my_variable}}即可引用该变量。
  4. 点击运行按钮，发送请求，实际运行的时候系统会将{{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。

本地值和远程值的区别

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

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

变量类型

  1. 环境变量 是最常用的变量，同一个变量可以在不同的环境设置不同的值，变量值会跟随环境切换而改变。环境变量在环境管理模块设置，查看文档：环境管理
  2. 全局变量 使用方法类环境变量类似，但全局变量不会跟随环境切换而改变。

  3. 临时变量 仅在单次运行接口用例或测试管理里的测试用例或测试套件过程中有效，不会持久化保存。

    使用变量

  4. 所有类型的变量都是通过双大括号的方式，如{{token}}。

  5. 接口运行tab、接口用例、快捷调试、集合测试的所有参数值、前置/后置脚本都可以使用变量。
  6. 环境里的额外参数也可以使用变量。

    提示 请求 Body 为 json 或者 raw 格式的，也可以直接使用变量、动态变量，使用方式如下： { “field1”: “{{stringVariable}}”, “field2”: {{intVariable}}, “field3”: {{arrayVariable}}, “field4”: {{objectVariable}}, “field5”: {{$timestamp}} } 注意：

    1. json 格式里 string 类型的值，使用变量的时候需要加上双引用；其他类型的值不要加双引号，如上面例子所示。
    2. 如果以没有加双引号的方式使用了变量，请不要使用格式化功能，如有提示 JSON 格式不正确，直接忽略即可。

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

  1. 变量user的值为如下格式对象：

    1. {
    2. "id": 1,
    3. "name": "jack"
    4. }
    1. 接口参数中以{{user.name}}方式引用user对象里的name属性值。
    2. 自定义代码中以pm.variables.get(“user.name”)方式引用user对象里的name属性值。

  2. 变量user的值为如下格式数组：

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

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

变量优先级

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

脚本中使用变量

环境变量

  1. // 设置环境变量
  2. pm.environment.set('variable_key', 'variable_value');
  4. // 获取环境变量
  5. var variable_key = pm.environment.get('variable_key');
  7. // unset 环境变量
  8. pm.environment.unset('variable_key');

将对象或数组（非字符串）写入环境变量
环境变量只能存在字符串，如要写入对象或数据，需要使用JSON.stringify转换成字符串

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

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

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

全局变量

  1. // 设置全局变量
  2. pm.globals.set('variable_key', 'variable_value');
  4. // 获取全局变量
  5. var variable_key = pm.globals.get('variable_key');
  7. // unset 全局变量
  8. pm.globals.unset('variable_key');

临时变量

  1. // 设置临时变量
  2. pm.variables.set('variable_key', 'variable_value');
  4. // 获取临时变量
  5. var variable_key = pm.variables.get('variable_key');
  7. // unset 临时变量
  8. pm.variables.unset('variable_key');

动态变量 / 随机参数

image.png
动态变量是在接口运行中按指定规则生成的变量

操作路径

在请求参数的示例值的位置，鼠标移动到输入框上时，会显示一个魔法棒的图标，点击即可设置动态变量 image.png

Socket接口

Socket 接口快速上手

注意

  • Apifox 版本号大于等于 1.1.0 才支持Socket接口管理。

示例场景

假设我们有一个宠物商店的项目，其中有一个 Socket 服务宠物资料服务，服务器的地址为:dev.server.com，端口为：9001。
该服务提供4个接口：

  1. 新建宠物资料
  2. 修改宠物资料
  3. 查询宠物资料
  4. 删除宠物资料

我们以新建宠物资料接口作为示例讲解。

【新建宠物资料】接口说明

请求报文
报文示例：

  1. 00000187<?xml version="l.0" encoding="UTF-8"?><data><name>Kitty 猫</name><photoUrl>http://dummyimage.com/400x400</photoUrl><tags>花斑</tags><categoryId>12</categoryId><status>pending</status></data>

报文说明：

  1. 前8位0000187为包头，存储包体的字节长度。
  2. 剩余部分为包体，为XML格式。
    1. XML 中节点存储需要新建的宠物资料数据。

返回报文
报文示例：

  1. 00000230<?xml version="l.0" encoding="UTF-8"?><data><errorCode>0</errorCode><data><name>Kitty 猫</name><photoUrl>http://dummyimage.com/400x400</photoUrl><tags>花斑</tags><categoryId>12</categoryId><status>pending</status></data></data>

报文说明：

  1. 前8位00000217为包头，存储包体的字节长度。

  2. 剩余部分为包体，为XML格式。

    1. XML 中节点表示状态码，0表示操作成功。
    2. XML 中节点存储新建成功的宠物资料数据。

      Apifox 操作示例

      一、创建服务

  3. 切换到SOCKET，然后新建 SOCKET 服务：image.png

  4. 填写宠物资料服务相关信息：image.png

    二、创建接口

  5. 在刚建的服务下添加接口：

image.png

  1. 填写接口相关信息：

image.png使用数据处理器，实际发送请求前对输入的数据进行处理：
1.计算内容长度并添加到包头：用来计算 XML 字节长度并添加到包头。
查看 数据处理器说明文档。

  1. 设置返回结果：

image.png使用数据处理器，对接口返回的数据进行处理后再展示：查看 数据处理器说明文档。

  1. 去除包头(指定包头长度)：去除返回数据里的包头（展示的时候不需要）。
  2. XML 转 JSON(可表单展示)：将返回包体里的 XML 转成 JSON 方便查看。

    三、运行接口

  1. 打开刚新建的接口，切换到“运行” tab，可以看到“报文内容”通过表单方式输入：

image.png

  1. 填写需要新建的宠物信息，点击“发送”即可发送请求并查看返回结果：

image.png

  1. 点击下方“Request” tab 即可查看实际发送的数据：

image.png

  1. 点击“Response”下的“原始报文”，即可查看接口返回的“报文原始内容”

image.png

四、保存为用例

“运行”接口后，建议点击右上方“保存为用例”，方便下次直接使用。

更多 Socket 功能

其他断言、提取变量、前置/后置脚本、测试管理里的测试用例和测试套件等功能的使用方法和 HTTP 接口是一致的，请参考相关文档。

报文数据处理器

数据处理器主要用来对发送或接收到的报文进行转换处理，包括以下 2 种数据处理器：

  1. 请求报文处理器
  2. 返回报文处理器

系统内置了一些常用的数据处理器，用户也可以添加自定义函数（写 Javascript 代码），以满足各种场景的需要。

一、请求报文处理器

主要用途：运行接口时对输入数据进行自动封装后再发送。
使用场景示例：

  1. 发送报文时，自动计算包体内容长度，添加到报文头部，然后再发送。
  2. 输入的 JSON 数据，转换为 XML 格式后在发送。

系统内置了一些常用的请求报文处理，如有特殊场景，用户可以添加自定义请求报文处理器。

二、返回报文处理器

主要用途：对返回的报文数据封装后再展示。
使用场景示例：

  1. 展示时去除报文头部。
  2. 将返回的 XML 转换成 JSON 格式。

系统内置了一些常用的返回报文处理，如有特殊场景，用户可以添加自定义返回报文处理器。

三、添加自定义处理器

点击项目设置->自定义函数，即可添加自定义处理器。