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 等数据类型，可以通过引用事先编辑好的 数据结构 来快速填写内容。系统也提供了导入功能方便您快速导入参数信息。