Eolink Apikit 创建/生成 API 文档

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

我们在接触了大量的客户后发现，采用 文档驱动 的协作模式会比先开发、后维护文档的方式更好，团队协作效率和产品质量都能得到提高。因此我们建议您尝试基于文档来进行工作，使用 文档驱动 方式来降低大量无意义的沟通成本。

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

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

创建 API 文档

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

私有云产品比线上 SaaS 产品支持更多的 API 协议，比如 Websocket、TCP、UDP、SOAP、HSF 等。

编辑 API 文档

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

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

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

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

API 请求参数

设置请求头部（request header）

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

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

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

设置请求体（request body）

请求体提供了五种类型：

1. Form-data（表单）

2. Json

3. XML

4. Raw（自定义文本类型数据）

5. 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 信息，如：

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

设置响应内容（response body）

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

1. Json

2. XML

3. Raw（自定义文本类型数据）

4. Binary（字节流、文件参数）

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