评测还在继续…
评测对象
- apidoc
- YApi[去哪儿]https://yapi.ymfe.org/
- NEI[网易云]https://nei.netease.com/
评测维度
- 编写方式
- UI
- 与仓库关联
- 监控仓库状态
- 导出PDF
- markdown
- 兼容性
- mock
- 接口调试
- 开源
- 自动化测试
- 插件
评测方式
通过以下方式得出评测结论
- 网站简介
- 提交频率
- 更新频率
- 产品示例
- 舆论口碑
注意：因为没有精力一一部署去测试，所以该评测在一定程度上不够客观。
评测结果
| APIDOC | YAPI | NEI | |
| 录入接口方式 | 注释/在线编辑 | 在线编辑 | 在线编辑 |
| UI/交互 | 二次开发 | 自带 | 自带 |
| 与仓库关联 | GIT/SVN | N | N |
| 监控仓库状态 | Y | N | N |
| 导出 | html,markdown,json | ||
| markdown | Y | N | N |
| 数据兼容性 | postman | postman/swagger/json | 貌似不支持导入 |
| mock | 根据接口示例生成 | 支持可编程mock | 支持可编程mock |
| 接口调试 | Y 需要是可以访问apidoc服务器的机器才可以 | Y | Y |
| 自动化测试 | N | Y | N |
| 开源 | Y | Y | Y |
| 插件 | 需要自行二次开发 | Y | 无 |
| 社区维护 | 现在仅有我们自己维护 | 持续维护 | 还有维护 |
评测总结
这里仅是根据上面数据的个人总结
- 关于录入接口的方式
- 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的方式。
下面提出一个思路以供参考：
- 从代码中的注释生成文档
- 然后为apidoc增加一个swagger的文档输出服务
- 再通过一个定时同步服务，将apidoc输出的swagger直接同步给YApi
- 这样，所有接口的文档部分由apidoc管理同步给YApi，接口的测试和MOCK能力由Yapi来处理