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

我会带着你远行 2022-05-16 01:52 695阅读 0赞

原文地址：[https://blog.csdn.net/diandianxiyu\_geek/article/details/81564132][https_blog.csdn.net_diandianxiyu_geek_article_details_81564132]

# 一、前言 #

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

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

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

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

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

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

# 二、接口文档在线平台 #

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

## 1.apizza ##

apizza的定位是**api协作管理工具** ，官网地址为 [https://apizza.net/][https_apizza.net]

他的首页是这样的

![这里写图片描述][70]

实际使用界面是这样的

![这里写图片描述][70 1]

![这里写图片描述][70 2]

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

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

### 1.1 文档导出html ###

导出的样子是这样的

![这里写图片描述][70 3]

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

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

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

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

## 2. YApi ##

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

[网站][Link 1]上的特性如下

![这里写图片描述][70 4]

他的界面是这样的

![这里写图片描述][70 5]

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

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

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

项目地址为 [https://github.com/ymfe/yapi][https_github.com_ymfe_yapi]

### 2.2 \[只能\]内网部署 ###

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

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

### 2.3 支持自动化测试 ###

![这里写图片描述][70 6]

### 2.4 支持导入 Postman HAR Swagger JSON ###

嗯！

### 2.5 支持导出 html markdown json ###

嗯！

## 3. RAP 2 ##

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

![这里写图片描述][70 7]

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

![这里写图片描述][70 8]

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

![这里写图片描述][70 9]

### 3.1 导出 Postman Collection ###

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

### 3.2 支持 mockjs ###

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

## 4. eolinker ##

[https://www.eolinker.com/][https_www.eolinker.com]

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

![这里写图片描述][70 10]

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

![这里写图片描述][70 11]

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

### 4.1 功能完善 ###

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

### 4.2 付费功能 ###

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

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

# 三、文档在线平台 #

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

## 1. 语雀 ##

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

![这里写图片描述][70 12]

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

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

![这里写图片描述][70 13]

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

## 2. 石墨文档 ##

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

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

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

![这里写图片描述][70 14]

## 3. Github的wiki ##

wiki有天生的优点

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

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

![这里写图片描述][70 15]

# 四、文件管理平台 #

## 1. Github ##

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

我们可以用于管理

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

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

# 五、总结 #

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

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

[https_blog.csdn.net_diandianxiyu_geek_article_details_81564132]: https://blog.csdn.net/diandianxiyu_geek/article/details/81564132
[https_apizza.net]: https://apizza.net/
[70]: /images/20220516/746f19c084b64a68a7a449309992dd7f.png
[70 1]: /images/20220516/a180e8fc3a0a49e79f89db6b7f9afa80.png
[70 2]: /images/20220516/2b4b9cab6c37474fbe8f7dbe722f159e.png
[70 3]: /images/20220516/a4d2110dac784c2989eaeb39fbe008db.png
[Link 1]: https://yapi.ymfe.org/
[70 4]: /images/20220516/7ba6d74976d641a9b9fc4b1613b33684.png
[70 5]: /images/20220516/03ed2aa5d3654956a381bda368e6be55.png
[https_github.com_ymfe_yapi]: https://github.com/ymfe/yapi
[70 6]: /images/20220516/83fb659dab774abe965bc3bc64c87b58.png
[RAP 2]: http://rap2.taobao.org/
[70 7]: /images/20220516/9459d4f8076d427ba256707b49d1bfcb.png
[70 8]: /images/20220516/3e2ea49ba935483c8ad7afb28471bcca.png
[70 9]: /images/20220516/f901c48c14774e958b8c0d5e93482dcf.png
[https_www.eolinker.com]: https://www.eolinker.com/
[70 10]: /images/20220516/73ad1bce3a8741deab5e54233bfd22e7.png
[70 11]: /images/20220516/722565a4aa0c45ec9bf9fdd78bd5d4b9.png
[https_public.eolinker.com_index_EOLINKER_20AMS_20FUNCTION_20DETAIL_2020180520.pdf]: https://public.eolinker.com/index/EOLINKER%20AMS%20FUNCTION%20DETAIL%2020180520.pdf
[https_www.yuque.com]: https://www.yuque.com/
[70 12]: /images/20220516/cf77390223cc42b59727aee7cd5b1259.png
[70 13]: /images/20220516/1e0952bfb3a54dc28de4f05f5c68f246.png
[Link 2]: https://shimo.im/
[70 14]: /images/20220516/2c37ca13f39449a1bed2e81094c88e04.png
[70 15]: /images/20220516/15fd4713c934497ab7252346d267bdc7.png