API 设计能做什么？

提示：

API 设计的主要作用是为了预先定义接口请求参数以及响应期望并生成 Mock URL，如果您仅仅需要调试接口，直接进 API调试 模块即可，无需在 API设计 模块预先定义。

API 设计用于在接口还没开发完成时，预定义接口请求参数和响应期望（Mock），并自动生成 Mock URL，让前端和测试提前进入研发流程。

一、预定义请求参数和响应期望

我们可以在 Apipost 的 API 设计模块预定义接口的 请求参数 和 响应期望（Mock），方便前端提前对接。如下图：

二、校验实际响应结果

当接口开发完成，准备进行调试时，我们也可以用在 API 设计中建立的响应期望 校验实际响应结果 是否符合预期。

API 设计-请求参数预定义

预定义请求参数

支持 header、query、body、认证四项，与 API 调试模块一致，共用同一份数据源。

Header 参数

你可以设置或者导入 Header 参数，cookie 也在 Header 进行设置

Query 参数

Query 支持构造 URL 参数，同时支持 RESTful 的 PATH 参数（如图中 :uid）

Body 参数

Body 提供三种类型 form-data / x-www-form-urlencoded / raw ，每种类型提供三种不同的 UI 界面 1）当你需要提交表单时，切换到 x-www-form-urlencoded

2）当你需要提交有文件的表单时，切换到 form-data

3）当您需要发送 JSON 对象或者其他对象时，切换到对应的 raw 类型即可

认证

支持 Digest auth、OAuth 1.0、Hawk Authentication、AWS Signature、NTML Authentication、Akamai EdgeGrid 六种认证方式。

API 设计-期望响应预定义

a、新建期望

在同一个接口里，由于我们对不同场景下返回的数据结构期望不同，我们可以通过设置多个期望的方式，来满足这个需求。 如图，点击【新建期望】即可打开新建期望的弹窗。我们可以选择该期望的状态码、填写期望名称、选择内容格式，填写触发条件（非必填），最后点击保存，该期望创建成功。

b.内容格式

我们可以选择 JSON、XML、 HTML、 Raw、 Binary 五种内容格式，其中 JSON 和 XML 格式可以通过增加字段节点来定义数据结构、字段类型、mock 值和参数描述，并支持导入 JSON、XML、JSON-schema 格式的文件，预览已编辑好的数据，支持刷新生成的数据。 1、JSON 格式：该格式的响应内容支持 json-schema、mock.js 两种各自独立的数据模式，我们可以选择一种方式建立期望，数据结构保存后，可以在响应示例中引用。

【json-schema 模式】

【mock.js 模式】

2、XML 格式：我们可以在 table 中配置，同 json-schema，数据结构保存后，可以在响应示例中引用。

【XML 模式】

3、HTML、Binary 格式：只展示格式名，不可手动配置内容，数据结构保存后，可以在响应示例中引用。

【HTML、Binary 格式】

c.字段类型

当我们选择 json-schema 或 XML 格式时，可以设置每一条字段的类型，分别为 string、number、integer、array、object、Boolean、null、any 八种类型，若需对该字段进行高级设置，不同的类型也对应不同的高级设置方法。

d.如何添加/删除字段

1、增加字段：默认展示 root 字段，当数据类型为 object，点击 root 右侧加号，可增加兄弟节点或子节点；当数据类型为 array，则自动增加一个 string 类型的子节点；当数据类型为 string、integer、Boolean、Number、null、any，可增加兄弟节点。

2、删除字段：点击删除 icon，直接删掉此字段（root 根节点不能删除）

e.高级设置

我们可以对某个字段进行高级设置，定义该字段数据结构的具体细节，同时也支持以目录为作用域进行定义，如点击根目录的高级设置，则高级设置内容对该目录下所有字段有效。

当数据类型为 string：

当数据类型为 integer：

当数据类型为 Boolean：

当数据类型为 array：

当数据类型为 object：

当数据类型为 Number：

当数据类型为 Null，则无高级设置。

当数据类型为 oneOf：

当数据类型为 anyOf：

当数据类型为 allOf：

f.智能期望

什么是智能期望？

我们可以在智能期望中填写一些触发条件，并设置当满足/不满足该触发条件后，所启用的期望。开启智能期望后，Apipost 会根据已设置的触发条件，匹配旗下的参数判断规则，若满足条件，则会启用预设的期望。

如何添加智能期望？

1、我们可以添加多个触发条件，每个触发条件下支持填写多个子条件。

2、填写好该触发条件下的子条件后，需要选择一个已有期望，作为满足该触发条件后所启用期望。

3、当触发条件下的所有子条件都被满足时，该触发条件才会被视为已满足。

获取自动生成的 Mock url

本地 url：是在本地进行的 mock 服务，只在本地可见，如需分享需要关闭防火墙。 云端 url：是在 Apipost 云服务上进行的 mock 服务，可以分享给他人，当关闭 url 链接后，分享出去的页面将不可见。

API 设计-保存并预览文档

我们在 API 设计模块所设置的内容，可以自动生成一篇文档以交付给前端，该文档包含了接口信息、请求参数、响应示例的所有内容。

响应示例：

1、生成示例：生成的文档默认不展示响应示例，我们可以通过点击 “生成全部示例” 按钮，生成所有已有期望所对应的响应示例，并自动提取其字段描述。

2、更新示例：点击每个响应示例右侧的“更新”按钮，则会更新为最新的响应示例。

编辑文档：支持在预览文档的代码框中编辑示列，点击“保存”按钮后生效。

分享文档：点击【分享文档】按钮后，我们可以设置分享的有效期和权限，并将该文档分享给他人。

API 设计与 API 调试的关系

1、互不制约：我们可以先进入 API 设计模块来设计 API，也可以直接进入 API 调试模块进行调试，不存在某一模块的内容没有手动写全，另一个模块没法进行的问题。

2、互相覆盖：在 API 设计中保存好的接口信息、全局参数、Mock URL，会同步到 API 调试模块，同理，当 API 调试模块有改动并保存后，也会同步到 API 设计模块。

3、灵活联动：在 API 设计中建立的响应期望，可以被引用到 API 调试的响应示例中，并可以通过校验功能，判断该响应期望的响应结果是否符合预期。