关于api: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 等数据类型，能够通过援用当时编辑好的 数据结构 来疾速填写内容。零碎也提供了导入性能不便您疾速导入参数信息。