最近公司打算做一个openapi开放平台,让我找一款好用的在线文档生成工具,具体要求如下:
- 必须是开源的
- 能够实时生成在线文档
- 支持全文搜索
- 支持在线调试功能
- 界面优美
说实话,这个需求看起来简单,但是实际上一点的都不简单。
我花了几天时间到处百度,谷歌,技术博客 和 论坛查资料,先后调研了如下文档生成工具:
gitbook
github地址:github.com/GitbookIO/g…
开源协议:Apache-2.0 License
Star: 22.9k
开发语言:javascript
用户:50万+
推荐指数:★★★
示例地址:www.servicemesher.com/envoy/intro…
gitBook是一款文档编辑工具。它的功能类似金山WPS中的word或者微软office中的word的文档编辑工具。它可以用来写文档、建表格、插图片、生成pdf。当然,以上的功能WPS、office可能做得更好,但是,gitBook还有更最强大的功能:它可以用文档建立一个网站,让更多人了解你写的书,另外,最最核心的是,他支持Git,也就意味着,它是一个分布式的文档编辑工具。你可以随时随地来编写你的文档,也可以多人共同编写文档,哪怕多人编写同一页文档,它也能记录每个人的内容,然后告诉你他们之间的区别,也能记录你的每一次改动,你可以查看每一次的书写记录和变化,哪怕你将文档都删除了,它也能找回来!这就是它继承git后的厉害之处!
优点:使用起来非常简单,支持全文搜索,可以跟git完美集成,对代码无任何嵌入性,支持markdown格式的文档编写。
缺点:需要单独维护一个文档项目,如果接口修改了,需要手动去修改这个文档项目,不然可能会出现接口和文档不一致的情况。并且,不支持在线调试功能。
个人建议:如果对外的接口比较少,或者编写之后不会经常变动可以用这个。
smartdoc
gitee地