eoLinker-AMS接口管理系统 API文档管理教程

创建接口分组

在eoLinker中，您可以为接口创建相应的分组以方便管理，AMS支持最多二级的接口分组。

创建分组

在API接口页面，点击分组侧边栏上方的 新建分组 按钮：

在弹出框中输入相关信息即可创建一个接口分组：

创建子分组

当鼠标放置于分组上时，右侧会出现 隐藏的菜单按钮：

点击之后选择 添加子分组 按钮，在弹出框中输入相关信息即可创建一个接口分组：

为什么不支持更多级分组？

经过实际的调研，当接口分组超过三级时，接口的管理/搜索效率反而是降低的，因此我们建议您如果项目的接口非常多，分级也比较复杂时，将项目合理拆分为几个项目会更好一些，比如拆分为用户系统、支付系统等。

------------------------------------------------------------------------------------------------------------

修改/删除接口分组

当鼠标放置于分组上时，右侧会出现 隐藏的菜单按钮：

点击之后选择 修改 或 删除 按钮即可：

------------------------------------------------------------------------------------------------------------

创建API接口

在项目详情页，点击侧边栏 API接口 ，进入API接口管理页面：

点击 新建接口 按钮，进入 API编辑页面 ：

页面上方是接口编辑的三大模块：

1. 基础信息：包含所有API相关的文档信息。eoLinker AMS提供目前业内最强大、全面的文档系统，一般情况下该文档系统已经可以满足80%以上的API管理需求。
2. 详细说明：eoLinker AMS提供了富文本以及Markdown双编辑器支持，您可以在此编写详细的API说明信息，并且支持插入图片！可以满足所有的API文档记录需求。
3. 高级Mock：提供自动生成Mock数据的功能，在此选项卡下可以编辑Mock数据的生成规则。eoLinker AMS全面支持MockJS并且在其之上进行了诸多优化，使得MockJS更加强大和易用。关于Mock的详细使用说明请查看 Mock章节。

基础信息中，首先填写API接口的必要信息：

1. 分组：最多支持二级分组，对API进行适当的归类有助于提高管理效率
2. 状态：表示当前API的运行状态【启用、维护、弃用】，仅作为标识方便核查
3. URL：API的地址，其中包括请求的方式，以及协议和路径，在此建议填写API的相对路径（如/user/login，忽略前面的www.xxx.com根路径），后期通过eoLinker AMS提供的强大的 环境管理 功能，统一改变所有API的根路径，相关的教程请看 环境管理章节
4. 名称：接口的描述
5. 星标★：注意右侧红色方框部分，您可以为接口标注星标，方便团队间沟通，如表示改接口存在Bug，或者表示需要对接等。

请求头部中，你可以手动输入接口的头部信息，也可以使用 导入头部 的功能批量导入：

注意，导入的每条头部信息之间通过 换行 表示结束，如：

1. Access-Control-Allow-Credentials:true
2. Access-Control-Allow-Headers:x-requested-with,content-type,Cache-Control,Pragma,Date,x-timestamp
3. Access-Control-Allow-Methods:POST, GET, OPTIONS
4. Access-Control-Allow-Origin:https://www.eolinker.com
5. Connection:keep-alive
6. Content-Length:0

请求参数部分，eoLinker提供了三种最常用的数据格式（红色部分）：

1. 智能表单[form-data]：支持无限层级结构，并且能对每个参数设定非常详细的示例和值可能性等，同时eoLinker提供了业内唯一的表单转Json方案，可以将表单转为同样格式的Json数据进行发送。
2. RESTful：支持无限层级结构，并且可以替换接口URL中的相关绑定参数。
3. 源数据[RAW]：所有非表单和Restful类型的参数均可通过源数据进行发送，如Json、XML或者其他自定义的数据格式等。

操作列（蓝色部分）分别是：

1. 参数的更多设置：如参数的值可能性（eoLinker首创功能，全面记录该参数拥有的各种值以及含义）、参数示例等。
2. 拖动排序
3. 删除

返回参数部分和请求参数部分大同小异，不做赘述。

返回示例 部分提供了 成功 以及 失败 两种结果的记录，同时返回记录也可以作为接口的简易Mock功能，当接口文档保存以后，将会得到两个统一前缀的URL地址，访问该地址可以得到实现记录好的 成功结果 或者 失败结果。

（上图为保存后的返回示例，红色部分的简易Mock的地址，访问即可得到相应的结果，如图中的返回结果为ok）

最后点击页面右上方的 保存 或者 继续添加 按钮，即可完成当前接口的创建工作。

熟练之后，创建一个接口文档的时间约为3~5分钟，并且可以连同接口测试一起进行，极大提高开发效率。

------------------------------------------------------------------------------------------------------------

修改接口

你可以在 接口列表 中，点击相关接口的 修改 按钮：

或者在 接口详情 页中，点击上方的 修改 按钮：

保存 & 快速保存

接口编辑完之后，可以选择保存或者快速保存来确认修改：

保存：要求修改人员填写修改的说明，方便其他人员进行对接以及后期维护；
快速保存：不要求写修改说明，直接保存。

如果是点击 保存 按钮，会弹出说明输入框来记录修改的日志：

------------------------------------------------------------------------------------------------------------

删除接口

你可以在 接口列表 中，点击相关接口的 删除 按钮：

或者在 接口详情 页中，点击上方 更多操作菜单 中的 修改 按钮：

*注意：以此方法删除的接口会进入 接口回收站，并不会直接删除。你还可以通过接口回收站进行 找回 或者 彻底删除，相关操作请看 接口管理-接口回收站 一节。

------------------------------------------------------------------------------------------------------------

接口回收站（恢复/彻底删除接口）

恢复接口

eoLinker AMS提供了 业内首创 的接口回收站功能，可以帮助找回误删接口，只要接口没有从回收站中删除，都可以恢复：

点击分组侧边栏中的 接口回收站：

找到右侧需要恢复的接口，点击恢复或者进行批量恢复，选择需要恢复到的分组即可：

彻底删除接口

点击分组侧边栏中的 接口回收站：

找到右侧需要彻底删除的接口，点击彻底删除或者进行批量删除即可：
*注意：一旦接口被彻底删除，将无法找回，请谨慎操作！

------------------------------------------------------------------------------------------------------------

接口版本管理

在eoLinker AMS中，你可以保存 所有API的操作历史，并且随时 回滚/切换 到任意一个版本，就像使用Github一样管理API。

进入接口详情页，点击上方 历史 选项卡，跳转到 版本管理页面：

列表中将会详细显示各版本的 修改时间、操作人员 以及 说明 等：

找到想要操作的版本，点击右侧的 切换 或 删除 按钮，即可 回滚/切换 或 删除 某个版本：

------------------------------------------------------------------------------------------------------------

eoLinker-AMS接口管理系统的API文档管理教程到这里就结束了，还有一部分全新的功能暂时就先不在这里放出了，最近有太多的事情要处理，大家有什么疑问不妨来我们的用户群里和我们聊聊哈（397452167）

来源：oschina

链接：https://my.oschina.net/u/3708797/blog/1607057