接口设计 (接口文档)

# 接口设计 (接口文档)

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

新人注意

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

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

新人常见问题

  • 如何像 Postman 那样不用提前设计接口就能快速调试? 使用 快捷调试 功能。
  • 如何固定 tab,避免新打开接口的时候覆盖掉已打开的 tab? 双击 tab 头或者双击树形菜单的对应内容,用法和 VS Code完全一样。(修改tab里的内容后,会自动固定 tab)

# 快速上手

  1. 点击左侧搜索框旁边的 + 号按钮即可打开新建窗口,也可使用 快捷键 Ctrl(⌘) + N。

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

# 接口路径

以斜杠/起始的接口 path 部分,如/pets/pets/{id}

注意

  1. 接口路径 建议不要包含 HTTP 协议及域名,这部分建议在 环境管理前置URL里设置,接口调试时的 URL 会自动加上当前环境的前置URL

  2. 特殊情况需在接口路径要带上HTTP 协议及域名的,系统也能支持,但不建议这么做。接口调试时,系统如检测到接口路径是以http://https://起始的,会自动忽略当前环境里前置 URL。

  3. Apifox 中的 Path 参数是以大括号包裹起来表示,而非冒号起始表示。正确示例/pets/{id}错误示例/pets/:id

  4. 接口路径 不可包含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 参数类型为jsonxml时,需要设置数据结构,并且数据结构可以引用数据模型,详细说明请查看文档:数据结构/数据模型

注意

  • 接口发送请求的时候会根据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

更多关于变量的说明请查看文档:环境变量/全局变量/临时变量

# 返回 Response

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

  • 接口返回的 HTTP 状态码
  • 返回内容的数据格式:JSONXMLHTMLRawBinary
  • 数据结构:仅JSONXML可配置数据结构,关于数据结构详细说明,请查看文档:数据结构/数据模型

注意

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

# 公共 Response

公共 Response主要用来实现 Response 的复用。

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

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

# 返回 Response 示例

设置返回 Response 的示例数据,方便查阅接口文档的人快速了解数据结构。

返回 Response 的示例数据也可以设置多次,点击返回 Response 示例模块右上方的+ 新建即可添加。建议至少设置两个示例:成功示例失败示例

# 其他

# OperationID

支持设置 OperationId属性,导出OpenAPI格式时会将此处的值导出到 Operation 对象的 OperationId 里

截屏2022-01-14 下午8.45.12