如何快速完成API设计，mock数据给到前端？

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调试的响应示例中，并可以通过校验功能，判断该响应期望的响应结果是否符合预期。