【工具】目前几种常见的线上接口文档管理平台的比较

一、前言

作为一个公司的技术部门,就会涉及到一些文档的对接,包括但不仅局限于

  • 需求文档
  • 会议记录
  • 接口文档
  • 切图标注

对接的部门,包括但不仅局限于

  • 前端和后端
  • 移动端和后端
  • 设计和前端
  • 设计和移动端
  • 产品经理和开发
  • 老板和产品经理

那么,在这些沟通中产生的文档,该怎么保存、归档,该怎么阅读、使用,就成了团队协作提升沟通效率中重要的一个环节。

接下来,我列举了一些工具,供开发人员和项目管理人员选择,根据自己的实际情况选出对应的解决方案。

二、接口文档在线平台

这里处理的问题是前端和后端交互,产生的一些接口文档,这些文档格式统一,但变更很快,并且修改之后看起来并不明显,如果开发团队有异地协作和远程办公,沟通又是个问题。

1.apizza

apizza的定位是api协作管理工具 ,官网地址为 https://apizza.net/

他的首页是这样的

这里写图片描述

实际使用界面是这样的

这里写图片描述

这里写图片描述

emmmm,实际上就是一个线上版本的Postman…

有几个亮点功能,如果你正好需要的话,可以酌情加分~

1.1 文档导出html

导出的样子是这样的

这里写图片描述

很方便前端和移动端的同学阅读,不知道比那些word文档强到哪里去了~

1.2 导入Postman.json和Swagger.json文件

如果团队内使用了Postman或者Swagger的话,就会让操作更加连贯。

如果可以导出对应的文件就好了~

2. YApi

YApi旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API

网站上的特性如下

这里写图片描述

他的界面是这样的

这里写图片描述

好吧,貌似开源的项目并不是都很好看……

2.1 源码开源&免费&支持二次开发

注意的是,这个项目是开放源代码的,也就意味着更安全,更可维护,你可以直接去反馈bug,让他做的更好。

项目地址为 https://github.com/ymfe/yapi

2.2 [只能]内网部署

项目开源带来的好处就是可以自己部署到内网上,保证数据的安全性。

同时YApi不提供公共的版本供大家注册使用,也就是需要我们自己的团队必须去部署。

2.3 支持自动化测试

这里写图片描述

2.4 支持导入 Postman HAR Swagger JSON

嗯!

2.5 支持导出 html markdown json

嗯!

3. RAP 2

为什么不是RAP呢,因为”RAP1功能不会再增加啦,新项目推荐使用RAP2哦”~
RAP 2是一个可视化接口管理工具,淘宝团队做的。
RAP1就不看了,直接看RAP2的网站。
经过注册登录,RAP 2的结构更像是Github。

这里写图片描述

有一个单独的状态页面展示全网的活跃度,说明你并不孤独。

这里写图片描述

其中接口的返回值是通过填写对应的数据和规则生成的,而不是复制对应的json,这样做更有利于测试工作。

这里写图片描述

3.1 导出 Postman Collection

看来大家都习惯于兼容Postman,这也间接说明了Postman这个工具的成功~

3.2 支持 mockjs

mockjs也是淘宝团队做的工具,“生成随机数据,拦截 Ajax 请求”。

4. eolinker

https://www.eolinker.com/

免费使用,API文档管理、自动化测试、开发协作利器

这里写图片描述

在经历过 注册 -> 验证邮箱 -> 填写问卷 -> 帮助指南 之后,实例项目的接口编辑页面是这样的

这里写图片描述

从使用者的角度来讲,这个的操作更加便利,虽然也是按Postman的样式去做的~

4.1 功能完善

eolinker是一款完整的商业化的接口管理工具,基本用到的功能,在上面都能找到,并且操作和用户体验做的都不错。

4.2 付费功能

功能完善的代价就意味着,如果你想要使用全部完善的功能,就要付费购买。

并且我们可以通过https://public.eolinker.com/index/EOLINKER%20AMS%20FUNCTION%20DETAIL%2020180520.pdf 来清晰的知道付费版的功能是哪些。

三、文档在线平台

上面的平台的针对性比较高,是专业的做接口文档的,还有一种是只做文档共享的,如果我们的目的是接口文档管理,针对性就会差一些。

1. 语雀

语雀 https://www.yuque.com/ 是蚂蚁金服做的一款文档编辑共享平台。

这里写图片描述

由于文档是可以全面公开的,所以,给我的感觉更像是简书。 :)

语雀以知识库作为文档的载体,可以选择在线编辑和分享给其他用户,注意是不能导出文件的哦。

这里写图片描述

如果作为内部工具使用的话,不是很推荐。

2. 石墨文档

石墨文档的侧重点更倾向于大家一起修改文件。

缺点也正是因为大家可以同时修改文件,造成的文件版本混乱。

石墨文档更倾向于存储一些定值的项目资料,而不是注重版本和变更的接口文档。

这里写图片描述

3. Github的wiki

wiki有天生的优点

  • 和项目绑定,这个项目的文档就写在这个项目的wiki中
  • 版本控制和历史回溯,因为和Github一样的管理方式,保证了良好的版本控制

缺点也在于,如果这个文档覆盖了多个项目,就只好单独开一个文档的项目。

这里写图片描述

四、文件管理平台

1. Github

本文中按范围的涉及越来越广,从局限使用和格式的专业接口管理平台,到限制文字不限制内容的文档管理平台,最终就指向了不限制文件格式的文件管理平台,那么这个非Github莫属了~

我们可以用于管理

  • 代码项目
  • 设计师设计和切图
  • 各种协议和文档
  • ……

限制越少,对应的复杂度也就越多,如果控制的接口文件格式排版不友好,带来的舒适度也会直线下降,不过这些都是没办法的。

五、总结

本文根据专业程度范围,讨论了这类在线管理平台的优缺点,列出了一些行业内常见的工具平台。

工具各种各样,都有自己存在的价值,更重要的是根据我们自己的实际需求,选择最适合自己的产品。

:)

阅读更多

扫码向博主提问

小雨同学_

博客专家

非学,无以致疑;非问,无以广识
去开通我的Chat快问
版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/diandianxiyu/article/details/81564132
所属专栏: 团队开发那些事儿
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

关闭
关闭
关闭