# 接口文档规范
## 前言
众所周知,拥有 `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,点击 **彻底删除** 按钮或者进行批量删除即可。