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

原创
2018/01/15 09:49
阅读数 719

创建接口分组

在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)

展开阅读全文
打赏
1
2 收藏
分享
加载中
更多评论
打赏
0 评论
2 收藏
1
分享
返回顶部
顶部