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

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

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

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

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

创建 API 文档

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

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

编辑 API 文档

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

API 状态：可以方便成员查看 API 当前所处的状态，并且进行状态流转的通知。
Tag 标签：可以作为 API 的备注或者是筛选条件。
负责人：当 API 文档内容发生变化时，负责人会自动收到 API 变更通知。

API 请求参数

设置请求头部（request header）

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

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

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

设置请求体（request body）

请求体提供了五种类型：

Form-data（表单）
Json
XML
Raw（自定义文本类型数据）
Binary（字节流、文件参数）

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

设置 Query 参数

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

/user/login?user_name=jackliu

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

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

设置 REST 参数

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

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

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

API 响应内容

设置响应头部（response header）

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

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

设置响应内容（response body）

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

Json
XML
Raw（自定义文本类型数据）
Binary（字节流、文件参数）

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

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

导出 API 文档

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

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

导出项目内所有 API 文档

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

导出项目支持以下格式：

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

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

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

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

导出分组内的 API 文档

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

导出分组支持以下格式：

Eolink Apikit
Word
PDF
Excel
Markdown

点击下一步跳转到选择导出的内容。

导出指定的 API 文档

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

选中需要导出的 API 数据，点击 导出按钮。

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

Eolink Apikit
Word
PDF
Excel
Markdown

点击下一步跳转到选择导出的内容。

选择导出的内容

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

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

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

筛选字段说明：

筛选 API 标签：可以筛选指定的 API 标签的数据。

筛选 API 标记：可以筛选有星标和无星标的 API 数据。

筛选 API 状态：可以筛选指定的 API 状态。

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

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

最后步骤

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

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

自动生成 API 文档，并支持动态更新通过注解自动生成 API 文档，并通过 OpenAPI 实现动态更新；
一键导入 Swagger、Postman、JMeter、RAP、YAPI 等产品数据；
通过界面快速创建 API 文档，支持导入各类数据报文直接生成文档内容；
首创的版本管理、差异对比、变更通知，像管理代码一样管理文档版本，并能快速对比版本，了解版本变动；
当API 发生变更时可自动通知相关人员，让内外部人员快速了解API变更情况，降低沟通成本。