众所周知,拥有 API
的应用程序项目,接口文档属于研发完整交付的一部分。生态上流行的接口文档工具数不胜数,其中有 Swagger
、apidoc
等。为了提高研发效力与交付速度,离不开工具利器,也就是说、接口文档的使用工具赋能,提高能效。
除此能效之外,还有团队统一工具的作用。
开发 API 接口时,必须要编写或生成接口的文档。
一个基本的接口文档,至少需要包含以下的内容:
目前所有接口文档统一使用基于 eolinker 的 API 管理系统 管理 API。
但由于 eolinker 该版本不支持代码自动生成接口文档,并且由于之前遗留的历史包袱,部分接口的分组和信息不是很完善。
目前管理后台和 wapapi 已有部分接口尝试使用 Swagger,不过还没正式部署。
TODO
eolinker 的 API 文档不支持自动生成,需要手动编写。
进入API开发管理页面,点击新建项目按钮,在弹框中输入项目名称等信息并点击确定保存即可。
API 列表中展示了丰富的 API 信息:
★ | APIs | URL | 创建者 | 最近更新者 | 更新日期 | 其他操作 |
---|---|---|---|---|---|---|
星标 | API 名称 | URL | API 创建人 | API 最后修改人 | API 更新日期 | 新窗口打开、修改、删除 |
API 列表提供了两种显示模式:
点击列表右上方的 排序 / 筛选 按钮,设置排序或筛选条件:
进入 API 文档 页面,点击 新建 API 按钮,进入到 API 编辑 页面。
最多支持三级分组,对 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、鉴权等信息。
请求头部中,可以手动输入接口的头部信息,也可以使用 导入头部 的功能批量导入:
Body 请求参数提供了两种类型:Form-data 或者 Raw。可以手动输入请求参数或者使用 导入 JSON / 导入 XML 功能来批量导入请求参数。
同时,Form-data 支持记录无限层级结构的请求参数,参数层级通过 “>>” 表示并且能对每个参数设定非常详细的示例和值可能性等:
在 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 信息时,可以通过使用 Markdown 或者富文本的方式来编写需要补充的信息:
进入 API 详情 页,点击 编辑 按钮即可进入 API 编辑页面:
删除单个 API
进入 API 列表 页面,点击接口的 删除 按钮;或者进入 API 详情 页,点击上方 其他操作 中的 修改 按钮。
以此方法删除的接口会进入 API 回收站,并不会直接删除,可以在 API 回收站中找回误删的 API。
批量删除 API
进入 API 列表 页面,点击 批量操作 按钮,选择需要删除的 API 之后,点击 移入回收站 按钮即可:
恢复 API
进入 API 回收站 页面,选择需要恢复的 API,点击 恢复 按钮或者进行批量恢复即可。
彻底删除 API
进入 API 回收站 页面,选择需要删除的 API,点击 彻底删除 按钮或者进行批量删除即可。