接口文档工具横向评测

2019-04-11

评测还在继续...

评测对象

apidoc
YApi[去哪儿]https://yapi.ymfe.org/
NEI[网易云]https://nei.netease.com/

评测维度

编写方式
UI
与仓库关联
监控仓库状态
导出PDF
markdown
兼容性
mock
接口调试
开源
自动化测试
插件

评测方式

通过以下方式得出评测结论

网站简介
提交频率
更新频率
产品示例
舆论口碑

注意：因为没有精力一一部署去测试，所以该评测在一定程度上不够客观。

评测结果

APIDOC

YAPI

NEI

录入接口方式

注释/在线编辑

在线编辑

UI/交互

二次开发

自带

与仓库关联

GIT/SVN

监控仓库状态

导出

PDF

html,markdown,json

PDF

markdown

数据兼容性

postman

postman/swagger/json

貌似不支持导入

mock

根据接口示例生成

支持可编程mock

接口调试

Y 需要是可以访问apidoc服务器的机器才可以

自动化测试

开源

插件

需要自行二次开发

无

社区维护

现在仅有我们自己维护

持续维护

还有维护

评测总结

这里仅是根据上面数据的个人总结

关于录入接口的方式
apidoc更全面更方便，更符合开发流程
YApi也可以，值得一提的是YApi支持的导入方式比较多，从某个角度来说也可以通过二次开发实现其他的录入方式
NEI仅支持在线录入方式
UI/交互
apidoc完全就是文档管理的界面交互，因为完全是公司的开发，很多细节还有待提高
YApi界面也还可以，满足基本需要
NEI的页面交互更像是一个项目管理的交互，而不是针对接口的
与代码仓库的关系
除了apidoc其他的平台都没有直接和代码仓库产生联系
YApi可以通过插件的方式，自己开发定时任务或者自己二次开发来跟仓库产生联系
导入导出
apidoc支持基本的pdf导出和postman及注释文件的导入，正在规划对swagger的支持
YApi的导入导出支持的格式比较多
NEI仅支持导出PDF
mock
apidoc仅支持对文档中示例的基本数据mock
YApi支持可编程的mock
NEI在mock方面支持的非常好
测试
apidoc仅支持数据结果的查看
YApi支持自动化测试
NEI支持单个或批量的接口测试
其他功能
apidoc支持markdown的文档输入方式，除了写接口文档，也支持添加技术文档，甚至可以用来记笔记
YApi提供二次开发插件的功能，可根据自己的需要自己开发功能
NEI仅有当前提供的功能，因为是开源也可以二次开发，但是社区对二次开发的支持度不高
社区维护
apidoc因为是个引擎，所以并没有什么社区维护，仅是根据当前的引擎做需要的开发
YApi现在的社区相对活跃，官方代码提交的频率也比较高
NEI的社区不是很活跃，代码提交频率也不是很高了，不知道会不会后面就没人维护了

写在最后

如果诉求是对文档进行维护和管理，当前内部开发的apidoc应该是首选，潜力也比较大。
但是要是说对接口本身和接口相关的体系进行管理，从外部开源的项目来看，NEI更优秀。
YApi虽然在两个方面都没有达到最好，但因为对插件开发的支持，以及灵活性，并不输NEI。
所以，如果需求只是对接口文档的管理，建议使用apidoc，同样的投入会得到更高的效果。
但是要对接口这边做全局的管理，可以用YApi+apidoc的方式。
下面提出一个思路以供参考：