接口设计入门

正如同建造房屋需要设计图纸，为软件开发功能时同样需要一份设计得当的接口方案。良好的接口设计方案可以使得 API 更加易于使用、维护与扩展，也能够降低团队在开发过程中因模糊定义而产生的阻塞。

开始设计接口

一份规范的接口设计应包含完整的接口路径、请求和响应格式、请求方法、路由、认证、功能参数、功能返回和错误处理等，以确保每项 API 的正确性和一致性。

进入 Apifox 的任意项目，点击左侧搜索框旁边的 + 号按钮，轻点“新建接口”按钮。你可以在新建的视窗中开始设计接口。

提示

与 Postman 有所区别，Apifox 区分接口设计和接口运行两个概念。

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

1. 填写接口路径

接口路径通常指的是 URL 地址，也称为端点（endpoint）。接口路径是 API 请求的入口和出口，通过接口路径向服务器发起请求，并获取服务器响应。

接口路径通常以斜杠/起始，例如/pets、/pets/{id}。

Apifox 中的 “Path 参数”以大括号包裹进行标识，而非以冒号起始进行标识。正确示例：/pets/{id}，错误示例/pets/:id。

URL 接口无需包含 HTTP 协议及域名信息，你可以在《环境管理》中的“前置 URL”中进行设置。不同的域名收归在不同的环境中，实际执行接口调试任务时，发送的请求将自动包含环境中配置的“前置 URL”。

若系统检测到接口路径以 http:// 或 https:// 起始，那么将自动忽略当前环境中配置的前置 URL。

2. 填写请求参数

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

Params 参数

Query 参数是接口请求中的一种参数传递方式，它通常用于传递一些可选的参数，比如过滤条件、排序方式、分页参数等。不建议直接将Query 参数，即 URL 中 ?后的参数直接写入至接口路径中。你可以直接将 Query 参数填写在下方的“请求参数”文本框中。

Path 参数

Path 参数也称为“路径参数”，是 API 请求中的一种参数传递方式。它能够使得请求的路径更加具体化，从而准确描述接口所操作的资源。它通常被大括号包含起来，在接口路径中作为参数占位符。例如 /pets/{id} 中的的 {id} 即表示名为id的 Path 参数。无需额外的参数，请求方只需要通过查看接口路径中所指定的宠物 ID 号，就可以直接判断接口目标。

Body 参数

当请求方发起 HTTP 请求时，通常需要带上一些参数以便服务器进行处理。这些参数可以通过 HTTP 请求头或者 HTTP 请求体传递给服务器。其中，通过 HTTP 请求体传递的参数被称为 Body 参数。Body 参数包含在请求的主体部分中，通常是一些表单数据、JSON 数据或者二进制数据。

Body 参数类型

• none：无 body 参数。
• form-data：表单数据。用户在前端界面填写表单信息后，通过 POST 或 PUT 等方法向服务器发送请求。表单数据通常会被编码为 application/x-www-form-urlencoded 或 multipart/form-data 格式作为请求的 Body 参数传递给服务器。
• x-www-form-urlencoded：此编码方式通常用于将表单数据编码后作为请求的 Body 参数传输到服务器。在该编码方式下，表单数据被编码为一系列键值对，每个键值对之间以 & 连接，并且键与值之间以 = 分隔。Content-Type 为application/x-www-form-urlencoded。
• json：在前端界面中通过 Ajax 技术向服务器发送请求时，可以将数据编码为 JSON 格式并作为请求的 Body 参数传递给服务器，服务器通常会使用相关的库来解析这些数据。Content-Type 为 application/json。
• xml：一种用于表示数据的标记语言。它不仅可以用于表示文本和图像等媒体类型，还可以用于表示结构化数据。 Content-Type 为 application/xml。
• binary：二进制数据。在上传文件或者图片等二进制数据时，可以将这些数据作为请求的 Body 参数传递给服务器，通常在请求头中也会指定这些数据的类型。
• raw：这是一种在 HTTP 请求体中发送原始数据的数据类型。在使用 RAW 参数的情况下，用户可以直接在请求体中指定需要发送的数据，而无需使用特定的编码方式或格式。这种方式比较灵活，可以用来发送各种类型的数据，包括纯文本、JSON、XML 等。

注意

• 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。

更多关于变量的说明请查看文档：《静态变量》。

查看返回响应

在接口发起请求后得到服务端返回响应。返回响应定义主要包含以下几部分：

• 接口返回的 HTTP 状态码
• 返回内容的数据格式：JSON、XML、HTML、Raw、Binary
• 数据结构：仅JSON、XML可配置数据结构。定义数据结构后，在进行接口调试时，系统会自动校验返回的数据是否符合定义的数据结构。关于数据结构详细说明，请查看《数据结构》。
• Mock 数据：系统会自动根据定义的数据结构 mock 出丰富可信的模拟数据，详细说明请参考《Mock 功能》。

如果一个接口在不同情况下返回不一样的数据结构，那么可以设置多个返回响应。点击返回响应模块右上方的 + 按钮进行添加。

设置响应示例

设置响应示例是 API 设计过程中非常重要的一个步骤。通过响应示例，请求者可以了解到 API 返回的数据结构、数据格式、数据内容等，从而更好地理解如何使用 API 接口。

点击响应示例模块右上方的+ 新建按钮即可添加多个示例，建议至少设置两个示例：成功示例、失败示例。

新建公共响应

公共响应功能可以理解为将某一个接口的响应作为模板并复用至其它接口。不同接口在某些情况下会返回相同的数据结构，如资源不存在(404)、没有访问权限(401)等。你可以将来这些返回设置为公共响应，避免重复编写，方便统一管理。

访问项目设置->公共响应，轻点右上角 “+” 按钮新建公共响应。

OperationID

接口支持设置 OperationId 属性，导出 OpenAPI 格式时会将此处的值导出到 Operation 对象的 OperationId 中。

常见问题

如何像 Postman 那样不用提前设计接口就能快速调试？

使用快捷请求功能。详细说明请参考《接口快捷请求》。

如何固定 tab，避免新打开接口的时候覆盖掉已打开的 tab？

双击 tab 头或者双击树形菜单的对应内容。用法与 VS Code 完全一样。修改 tab 里的内容后，会自动固定 tab 页。