Apifox软件使用技巧：Apifox接口设计 (接口文档)的应用

软件开发过程中，接口管理、调试、自动化测试是必不可少的，我们经常使用 Postman 等工具来进行接口调试，在接口调试方面 Postman 做的非常出色。但是在整个软件开发过程中，接口调试只是其中的一部分，还有很多事情 Postman 无法完成，或者无法高效完成，比如：接口文档定义、Mock 数据、接口自动化测试等等。而 Apifox 就是为此而生的。那我们今天就来说说Apifox接口设计 (接口文档)。

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

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

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

如何像 Postman 那样不用提前设计接口就能快速调试？ 使用 快捷调试 功能。
如何固定 tab，避免新打开接口的时候覆盖掉已打开的 tab？ 双击 tab 头或者双击树形菜单的对应内容，用法和 VS Code完全一样。
快速上手
点击左侧搜索框旁边的 + 号按钮即可打开新建窗口，也可使用 快捷键 Ctrl(⌘) + N。

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

接口路径
以斜杠/起始的接口 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：发送其他文本类数据时使用。
注意

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

接口发送请求的时候会根据Body 参数类型自动在请求Header加上对应的Content-Type，无需手动设置。
若需要手动设置Header中的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。

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

返回 Response

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

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

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

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

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

返回 Response 示例

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