【接口自动化测试】Eolink Apikit 如何生成与导出接口文档?

在 API 研发管理产品中,几乎所有的协作工作都是围绕着 API 文档进行的。

采用文档驱动的协作模式会比先开发、后维护文档的方式更好,团队协作效率和产品质量都能得到提高。基于文档来进行工作,使用文档驱动方式可以降低大量无意义的沟通成本。

创建了 API 文档之后,可以随时查看 API 的改动情况、根据 API 文档发起 API 测试、编写 API 测试用例、使用 Mock API 等。

如下图,在 Eolink Apikit 系统中管理的 API 文档,可以详细的看到 API 的描述信息、变更历史、测试用例、Mock API 等内容。

1


创建 API 文档

在项目详情页点击左侧 API 文档 功能,进入API管理页面,点击 添加 API,会进入 API 创建页面。

Eolink Apikit 具备目前市面最全协议支持能力,并免费提供给所有用户,支持 DUBBO HTTP/HTTPS REST Websocket/Websockets gRPC TCP UDP SOAP HSF 等协议。

2


编辑 API 文档

在 API 描述标签页中填写 API 的请求路径、API 名称、标签、负责人等基本信息:

  1. API 状态:可以方便成员查看 API 当前所处的状态,并且进行状态流转的通知。

  2. Tag 标签:可以作为 API 的备注或者是筛选条件。

  3. 负责人:当 API 文档内容发生变化时,负责人会自动收到 API 变更通知。

3


API 请求参数

设置请求头部(request header)

可以输入或导入请求头部。

4

批量导入的数据格式为 key : value ,一行一条 header 信息,如:

Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

5

6

设置请求体(request body)

请求体提供了五种类型:

  1. Form-data(表单)
  2. Json
  3. XML
  4. Raw(自定义文本类型数据)
  5. Binary(字节流、文件参数)

对于 Form-data(表单)、Json、XML 等数据类型,可以通过引用事先编辑好的数据结构来快速填写内容。

7

设置 Query 参数

Query 参数指的是地址栏中跟在问号 ? 后面的参数,如以下地址中的 user_name 参数:

/user/login?user_name=jackliu

批量导入的数据格式为 ?key=value… ,通过&分隔多个参数,如:

api.eolinker.com/user/login?user_name=jackliu&user_password=hello

8

设置 REST 参数

REST 参数指的是地址栏被斜杠/分隔的参数,如以下地址中的使用大括号包裹起来的 user_name、user_password 参数:

/user/login/{user_name}/{user_password}

注意:只需要在 URL 中使用 {} 将 REST 参数括起来。API 文档和测试时,下方表格的参数名不需要使用 {}。

9


API 响应内容

设置响应头部(response header)

可以输入或导入响应头部,批量导入的数据格式为 key : value ,一行一条 header 信息,如:

Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

10

设置响应内容(response body)

响应内容的编写方式和请求参数的类似,响应内容提供了四种类型:

  1. Json
  2. XML
  3. Raw(自定义文本类型数据)
  4. Binary(字节流、文件参数)

对于 Json、XML 等数据类型,可以通过引用事先编辑好的数据结构来快速填写内容,系统也提供了导入功能方便快速导入参数信息。

11

体验地址:https://www.eolink.com/apikit


导出 API 文档

Eolink Apikit 可以将项目的 API 文档导出为多种离线格式,方便分享给团队以外的人。导出方式分为 3种:

  • 导出项目内所有 API 文档
  • 导出分组内的 API 文档
  • 导出指定的 API 文档

导出项目内所有 API 文档

  1. 在左侧栏的项目管理中,选择二级菜单项目设置,底部其他操作中点击导出项目。

12

导出项目支持以下格式:

  • Eolink Apikit 项目数据
  • Eolink Apikit API 相关数据
  • HTML
  • Word
  • PDF
  • Excel
  • Markdown
  • Swagger JSON
  • Swagger YAML

Eolink Apikit 项目数据 和 Eolink Apikit API 相关数据的差异在于,前者除了包含 API 相关数据外,还包含了状态码、项目文档、环境、数据结构等项目级公共数据。后者仅支持 API 文档、测试用例、高级 Mock 等数据。

  1. 第一选项 Eolink 项目数据(.json) 是将当前项目所有 API 数据进行导出,点击确定就可以进行导出操作。

13

  1. 其他格式会显示下一步按钮点击下一步跳转到选择导出的内容。

14

导出分组内的 API 文档

  1. 在左侧栏的 API 点击,选择需要导入的分组,点击下拉框选择导出 API 。

15

导出分组支持以下格式:

  • Eolink Apikit
  • Word
  • PDF
  • Excel
  • Markdown
  1. 点击下一步跳转到选择导出的内容。

16

导出指定的 API 文档

  1. 在左侧栏的 API 点击,选择需要导入的分组或点击 所有 API,点击右侧 API 列表标签页下的批量操作按钮。

17

  1. 选中需要导出的 API 数据,点击 导出按钮。

18

导出指点 API 文档支持以下格式:

  • Eolink Apikit
  • Word
  • PDF
  • Excel
  • Markdown
  1. 点击下一步跳转到选择导出的内容。

19

选择导出的内容

  1. 如果是选择导出项目内所有 API 文档方式,则左侧栏显示筛选 API 分组,右侧栏显示选择筛选条件。

20

  1. 如果是选择导出分组内 API 文档方式,则显示选择筛选条件。

21

  1. 如果是导出指定的 API 文档,则显示筛选条件,并且只显示额外导出内容。

22

筛选字段说明:

  1. 筛选 API 标签:可以筛选指定的 API 标签的数据。

  2. 筛选 API 标记:可以筛选有星标和无星标的 API 数据。

  3. 筛选 API 状态:可以筛选指定的 API 状态。

  4. 额外导出内容:可以筛选 API 返回示例和 API 详细说明等信息 (execl 和 Swagger 不支持该选项)。

  5. 导出环境:可以导出指定的项目环境( Eolink Apikit 不支持该选项)。

最后步骤

  1. 点击确定后, 显示成功提示,并且右侧栏显示我的任务队列状态为进行中,成功后就可以点击下载到本地了。

23


Eolink Apikit = API 管理 + Mock + 自动化测试 + 异常监控 + 团队协作,快速生成和管理所有 API 文档, 无论使用什么语言开发,Apikit 都可以统一规范地管理起来,并提供强大的文档管理、协作、测试、分享功能。

  • 自动生成 API 文档,并支持动态更新通过注解自动生成 API 文档,并通过 OpenAPI 实现动态更新;

  • 一键导入 Swagger、Postman、JMeter、RAP、YAPI 等产品数据;

  • 通过界面快速创建 API 文档,支持导入各类数据报文直接生成文档内容;

  • 首创的版本管理、差异对比、变更通知,像管理代码一样管理文档版本,并能快速对比版本,了解版本变动;

  • 当API 发生变更时可自动通知相关人员,让内外部人员快速了解API变更情况,降低沟通成本。

评论

暂无评论