526互联

Apifox使用-接口设计

发布时间 2023-07-28 19:58:41作者: 天才九少

官网：https://apifox.com/

帮助文档：https://apifox.com/help/

正文

  1. 接口管理痛点
  2. 使用场景和最佳实践
  3. Apifox使用：团队与项目
  4. Apifox使用：接口文档设计

 （1）接口管理痛点​

大多数研发团队通常会使用以下多种工具管理 API 接口：

  • 使用 Swagger 管理 API 文档
  • 使用 Postman 调试 API
  • 使用 mockjs 等工具 Mock API 数据
  • 使用 JMeter 做 API 自动化测试

维护不同工具之间数据一致性非常困难、低效。并且这里不仅仅是工作量的问题，更大的问题是多个系统之间数据不一致，导致协作低效、频繁出问题，开发与测试人员痛苦不堪。许多研发团队正在经历以下庞杂的协作场景：

  • 架构师在 Swagger 定义好 API 文档后，调试接口时还需要再去 Postman 定义一遍。
  • 前端工程师在开发 Mock 数据时需要在 mockjs 进行定义，还需要手动设置 Mock 规则。
  • 前端工程师根据 mockjs Mock 返回的数据完成开发，后端工程师根据 Swagger 定义的接口文档进行开发，并且各自都通过了测试流程。结果在进入前后端对接流程时又发现各项不一致问题：
    1. 开发过程中接口变更了，只修改了 Swagger，但是没有及时同步修改 mockjs。
    2. 后端开发的接口数据类型和文档不一致，肉眼难以发现问题。
  • 测试工程师在 JMeter 写好的测试用例，真正运行的时候发现接口有更新，导致需要重复回到 JMeter 重新定义接口参数。

随着开发周期的推移，因为团队中存在过于复杂的工具链路，使得每个环节中的不一致性趋于混乱；开发人员的心智负担越来越重，最终变成了整个团队积重难返的技术债务。而 Apifox 能够有效的解决上述问题

 （2）使用场景和最佳实践

Apifox = Postman + Swagger + Mock +JMeter

使用场景

  • 前端开发

    • 接口文档管理
    • 接口数据 Mock
    • 接口调试
    • 前端代码自动生成

  • 后端开发

    • 接口文档管理
    • 接口调试
    • 接口自动化测试
    • 后端代码自动生成

  • 测试人员

    • 接口调试
    • 接口自动化测试

最佳实践​

  1. 前端（或后端）在 Apifox 上定好接口文档初稿。
  2. 前后端 一起评审、完善接口文档，定好接口用例。
  3. 前端 使用系统根据接口文档自动生成的 Mock 数据进入开发，无需手写 mock 规则。
  4. 后端 使用接口用例 调试开发中接口，只要所有接口用例调试通过，接口就开发完成了。如开发过中接口有变化，调试的时候就自动更新了文档，零成本的保障了接口维护的及时性。
  5. 后端 每次调试完一个功能就保存为一个接口用例。
  6. 测试人员 直接使用接口用例测试接口。
  7. 所有接口开发完成后，测试人员（也可以是后端）使用集合测试功能进行多接口集成测试，完整测试整个接口调用流程。
  8. 前后端 都开发完，前端从Mock 数据切换到正式数据，联调通常都会非常顺利，因为前后端双方都完全遵守了接口定义的规范。

 （3）Apifox使用：团队与项目

团队：一个团队可以有多个项目和成员，团队之间的数据相互独立且互不可见

团队的主要功能包括：

  • 成员管理：即可以拉人进团队也可以踢人，要给不同的分配不同的角色
  • 权限控制：根据不同的角色分配不同的权限
  • 协作：包括协同编辑、资源共享、交流讨论等

（1）成员管理

包括管理团队和管理团队成员

 团队管理包括：创建团队、更改团队信息、退出团队、移交团队、解散团队这么几个功能

在团队页面，点击 「成员/权限」->「邀请成员」，进行邀请

进入「我的团队」->「成员/权限」，点击对应成员的「设置」图标，即可对成员进行权限设置。 成员权限分为团队权限和项目权限

创建团队：做出导航栏-新建团队

更改团队信息：「团队设置」->「基础信息」->「编辑」

移交团队：「团队设置」->「危险区域」->「移交」

解散团队：「团队设置」->「危险区域」->「解散」

退出团队：「团队设置」->「危险区域」->「退出」

团队成员可以退出团队

（2）项目管理

这一块包括的功能有：创建项目、编辑项目、克隆项目、移动项目、删除项目

创建项目：「团队项目」->「新建项目」->「确定」

编辑项目：「项目设置」->「基础设置」->「编辑」

克隆项目：通过「项目设置」->「基础设置」->「克隆」，可克隆项目到当前团队或其他团队

移动项目：移动项目：通过「项目设置」->「基础设置」->「移动项目」，将项目移动到其他团队。

删除项目：通过「项目设置」->「基础设置」->「删除」，将项目彻底删除

 

 

（4）Apifox使用：（接口文档设计）

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

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

新建接口

设计接口文档 

1，设定接口路径

在接口路径填写路径即可，不需要填写http协议及域名

在接口路径框中以斜杠/起始的接口 path 部分，如/pets、/pets/{id}

 注意事项：

  1. 接口路径 建议不要包含 HTTP 协议及域名，这部分建议在 调试环境 的前置 URL里设置，接口调试时的 URL 会自动加上当前环境的前置 URL。相当于jmeter里面的HTTP请求默认值
  2. 特殊情况需在接口路径要带上HTTP 协议及域名的，系统也能支持，但不建议这么做。接口调试时，系统如检测到接口路径是以http://或https://起始的，会自动忽略当前环境里前置 URL。
  3. Apifox 中的 Path 参数是以大括号包裹起来表示，而非冒号起始表示。正确示例：/pets/{id}，错误示例/pets/:id。
  4. 接口路径 不可包含Query 参数（即 URL 中 ?后的参数），Query 参数在下方请求参数部分填写。

2，指定请求方式

  1. GET（获取）：用于获取指定资源，不应产生副作用，使用查询参数传递参数。
  2. POST（提交）：用于提交数据，可能产生副作用，可以传递请求体参数。
  3. PUT（更新）：用于更新或替换指定的资源。
  4. DELETE（删除）：用于删除指定的资源。
  5. OPTIONS（选项）：用于获取目标资源支持的请求方式。
  6. HEAD（请求头）：与 GET 类似，但只返回响应头部，用于检查资源是否存在和是否修改。
  7. PATCH（补丁）：用于更新指定资源的部分信息。
  8. TRACE（跟踪）：用于回显服务器收到的请求，用于调试和诊断。
  9. CONNECT（连接）：用于建立与服务器的网络连接，通常用于代理服务器的请求转发。

3，请求参数

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

Params 参数

不建议直接将Query 参数，即 URL 中 ?后的参数直接写入至接口路径中。你可以直接将 Query 参数填写在下方的“请求参数”文本框中

 Path 参数

Path 参数也称为“路径参数”，它通常被大括号包含起来，在接口路径中作为参数占位符。例如 /pets/{id}

Body 参数

通过 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。
    • 示例：如 Body 参数类型为form-data，手动设置Content-Type的值为multipart/form-data; charset=GBK是有效的；但如果把值设置为application/json则会被系统忽略掉，因为和参数类型不匹配。
    • Body 参数类型为raw时，手动设置Content-Type的值不受限制。

4，提供响应

返回响应定义主要包含以下几部分：

  • 接口返回的 HTTP 状态码
  • 返回内容的数据格式：JSON、XML、HTML、Raw、Binary
  • 数据结构：仅JSON、XML可配置数据结构。定义数据结构后，在进行接口调试时，系统会自动校验返回的数据是否符合定义的数据结构。
  • Mock 数据：系统会自动根据定义的数据结构 mock 出丰富可信的模拟数据
  • 如果一个接口在不同情况下返回不一样的数据结构，那么可以设置多个返回响应。点击返回响应模块右上方的 + 按钮进行添加，建议至少设置两个示例：成功示例、失败示例

 公共响应

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

设置方法：打开项目设置->公共响应，在这里管理公共响应。

5，在线文档

点击左侧菜单栏中的“在线分享”选项，轻点“发布”按钮即可完成在线文档发布。

 

个人学习研究用，详细请查看官方帮助文档