API设计
API设计的主要作用是为了满足研发人员APIfirst的开发习惯,可以预先定义接口请求参数以及响应期望,如果您仅仅需要调试接口,直接进 调试 页面即可,无需在 设计 页面预先定义。
接口基本信息
在设计tab下可对接口进行开发状态、标签、拓展属性(项目设置中设置) 的定义,已经当对接口需要更加详细,有图标、或表格类的描述时,可在详细说明下的Markdown进行编辑描述
定义接口请求参数
可直接可视化定义接口的请求header、query等入参,当项目下的接口都有一个公共的请求参数时,可以使用全局参数
的功能快速设置整个项目的公共入参。
Header
设置header入参,支持下拉快速查找常用的header参数名
- 支持设置参数的类型
- *星号:表示该参数是否必填
- 参数值:表示一个入参的示例值
- 参数描述:对该参数的一个含义描述(支持快速填充,可了解
参数描述库
功能)
Query
设置query入参
- 支持设置参数的类型
- *星号:表示该参数是否必填
- 参数值:表示一个入参的示例值
- 参数描述:对该参数的一个含义描述(支持快速填充,可了解
参数描述库
功能)
Body
设置body入参:支持多种数据格式 none
form-data
urlencode(即x-www-form-urlencoded)
binary
raw(json/xml/javascript/plain/html)
- none 格式表示body无请求正文
- form-data 格式支持上传文件以及选择内容类型:当你需要提交有文件的表单时,切换到 form-data
- urlencode(即x-www-form-urlencoded)格式:当你需要提交表单时,切换到 urlencoded
- 当您需要发送JSON对象或者其他对象时,切换到对应的raw类型即可 raw(json/xml)格式,支持数据结构(可以了解数据结构的使用)设计带层级接口的json或xml的入参参数值
raw(javascript/plain/html)支持源码编辑方式设计入参的参数值
Path
支持RESTful API设计,通过在接口路径中{}
或 :
的方式增加变量,添加后也会在入参中展示出来
认证
支持Bearer auth认证、Basic auth认证、Digest auth认证、OAuth 1.0、Hawk authentication、AWS Signature、NTLM Authentication(Beta)、Akamai EdgeGrid八种认证方式。
定义接口响应期望
新建期望
在同一个接口里,由于我们对不同场景下返回的数据结构期望不同,我们可以通过设置多个期望的方式,来满足这个需求。 如图,点击【新建期望】,我们可以选择该期望的状态码、填写期望名称、选择内容格式,点击【确定】新建成功
设计数据结构
我们可以选择JSON
、XML
、 HTML
、 Binary
四种内容格式,其中JSON/XML
格式可以通过可视化的方式设计响应期望返回的数据结构(可以了解数据结构的使用)
设计响应示例值
设计好的数据结构也可以mock生成响应示例值
Mock服务
在接口还没开发完成时,定义完接口的请求参数和响应期望,可以自动生成 Mock URL,让前端和测试提前进入研发流程。
Apipost提供了智能Mock服务支持填写一些触发条件,并设置当满足/不满足该触发条件后,所启用的期望。开启智能期望后,Apipost会根据已设置的触发条件,匹配旗下的参数判断规则,若满足条件,则会启用预设的期望。具体使用可查看相关文档