# 接口文档规范
## 前言
众所周知，拥有 `API` 的应用程序项目，接口文档属于研发完整交付的一部分。生态上流行的接口文档工具数不胜数，其中有 `Swagger`、`apidoc` 等。为了提高研发效力与交付速度，离不开工具利器，也就是说、接口文档的使用工具赋能，提高能效。
除此能效之外，还有团队统一工具的作用。
## 规范
开发 API 接口时，必须要编写或生成接口的文档。
一个基本的接口文档，至少需要包含以下的内容：
- 接口说明：包括接口功能描述、接口地址、请求头要求、请求方式
- 请求示例
- 请求参数说明：包括字段名称、字段说明、字段类型、是否必填、字段示例
- 响应示例
- 响应参数说明：包括包括字段名称、字段说明、字段类型、是否必定有值、字段示例
## 工具
目前所有接口文档统一使用基于 eolinker 的 [API 管理系统](https://api-mg.ywtinfo.com/) 管理 API。
> 但由于 eolinker 该版本不支持代码自动生成接口文档，并且由于之前遗留的历史包袱，部分接口的分组和信息不是很完善。
> 目前管理后台和 wapapi 已有部分接口尝试使用 Swagger，不过还没正式部署。
### Swagger
*TODO*
### eolinker
eolinker 的 API 文档不支持自动生成，需要手动编写。
#### 创建项目
进入API开发管理页面，点击新建项目按钮，在弹框中输入项目名称等信息并点击确定保存即可。
#### API 列表简介
API 列表中展示了丰富的 API 信息:
| ★ | APIs | URL | 创建者 | 最近更新者 | 更新日期 | 其他操作 |
|---|
| 星标 | API 名称 | URL | API 创建人 | API 最后修改人 | API 更新日期 | 新窗口打开、修改、删除 |
- 切换 API 列表显示模式
API 列表提供了两种显示模式：
1. 详细模式：会在列表中显示详细的信息；
2. 省略模式：仅会显示 API 的基础信息（API 名称、URL）。
- 点击列表右上方的 详细 / 省略 按钮，切换合适的显示模式：
- API 列表排序 & 筛选
点击列表右上方的 排序 / 筛选 按钮，设置排序或筛选条件：
#### 创建 API
- API 基本信息
进入 **API 文档** 页面，点击 **新建 API** 按钮，进入到 **API 编辑** 页面。
- 设置 API 分组
最多支持三级分组，对 API 进行适当的归类有助于提高管理效率。
- 设置 API URL 以及 API 名称
如果有多个项目环境，不同的项目环境拥有不同的请求 URL 前缀，那么 URL 仅需要填写 API 的路径即可（如 / user/login），切换不同的 URL 前缀可以使用 eoLinker AMS 中的环境管理功能。相关教程请前往 **API 开发管理 > 公共资源管理 > 环境管理** 一节。
设置 API 状态
在 eoLinker AMS 中，API 拥有以下的几种状态：
| 状态 | 描述 |
|---|
| 启用 | 当前 API 正常使用 |
| 维护 | 当前 API 正在维护，不建议使用 |
| 弃用 | 当前 API 已经停用，不建议使用 |
| 待定 | 当前 API 尚未开发，需求待定 |
| 开发 | 当前 API 正在开发 |
| 测试 | 当前 API 正在测试 |
| 对接 | 当前 API 正在对接调试 |
| BUG | 当前 API 出现 BUG，建议尽快修复 |
- 请求信息
在 API 文档中，可以记录 Header、Request Body、REST Params、Query/GET Params、鉴权等信息。
- 设置 Header
请求头部中，可以手动输入接口的头部信息，也可以使用 **导入头部** 的功能批量导入：
- 设置 Request Body
Body 请求参数提供了两种类型：Form-data 或者 Raw。可以手动输入请求参数或者使用 **导入 JSON** / **导入 XML** 功能来批量导入请求参数。
同时，Form-data 支持记录无限层级结构的请求参数，参数层级通过 “>>” 表示并且能对每个参数设定非常详细的示例和值可能性等：
- 设置 REST Params
在 eoLinker AMS 中，REST 参数在 URL 中使用 **{param_name}** 表示，如 **/user/login/{user_name}/{user_type}**，该 API 拥有 REST 参数 user_name 和 user_type。
注意，只需要在 URL 中使用 {} 将 REST 参数括起来，下方的表格中不需要使用{}。
- 返回参数
可以手动输入请求参数或者使用 **导入 JSON** / **导入 XML** 功能来批量导入请求参数。
- 返回示例
可以记录 API 请求成功或失败的示例，eoLinker AMS 提供了 API 来获取编写好的 API 返回示例，可以用于前端开发人员测试 API。
保存 API 文档之后，通过返回示例 API 即可获得事先编写好的返回示例：
- API 详细文档
当 API 文档无法详细地记录下 API 信息时，可以通过使用 Markdown 或者富文本的方式来编写需要补充的信息：
#### 管理 API
- 修改 API
进入 **API 详情** 页，点击 **编辑** 按钮即可进入 API 编辑页面：
- 删除 API
删除单个 API
进入 **API 列表** 页面，点击接口的 **删除** 按钮；或者进入 **API 详情** 页，点击上方 **其他操作** 中的 **修改** 按钮。
> 以此方法删除的接口会进入 **API 回收站**，并不会直接删除，可以在 API 回收站中找回误删的 API。
批量删除 API
进入 **API 列表** 页面，点击 **批量操作** 按钮，选择需要删除的 API 之后，点击 **移入回收站** 按钮即可：
- API 回收站
恢复 API
进入 **API 回收站** 页面，选择需要恢复的 API，点击 **恢复** 按钮或者进行批量恢复即可。
彻底删除 API
进入 **API 回收站** 页面，选择需要删除的 API，点击 **彻底删除** 按钮或者进行批量删除即可。