前言最近公司打算搭建一个openAPI开放平台。让我找一个简单易用的在线文档生成工具。具体要求如下：必须开源实时生成在线文档，支持全文搜索，支持在线调试，界面美观。说实话，这个需求看似简单，其实一点都不简单。找了几天资料，研究了以下文档生成工具：gitbookgithub地址：https://github.com/GitbookIO/gitbook开源协议：Apache-2.0许可星级：22.9k开发语言：javascript用户:500,000+推荐指数：★★★示例地址：https://www.servicemesher.com/envoy/intro/arch_overview/dynamic_configuration.htmlgitBook是一个文档编辑工具。其功能类似于金山WPS中的word文档编辑工具或微软Office中的word文档编辑工具。可以用来写文档，创建表格，插入图片，生成pdf。当然以上功能WPS和office可能做的更好，但是gitBook还有更强大的功能：它可以用文档建一个网站，让更多人了解你写的书。另外，最核心的是，他支持Git，也就是说它是一个分布式的文档编辑工具。您可以随时随地编写您的文档，并且可以多人一起编写文档。就算多人写文档的同一页，它也可以记录每个人的内容，然后告诉你他们的区别，它也可以记录你的每一页。一旦修改，可以查看每条书写记录和修改，即使删除文件也可以找回！这就是继承了git之后它的强大之处！优点：使用非常简单，支持全文搜索，可以和git完美集成，无需嵌入任何代码，支持markdown格式的文档编写。缺点：需要单独维护一个文档项目。如果修改了界面，需要手动修改文档项目，否则可能会出现界面和文档不一致的情况。另外，不支持在线调试功能。个人建议：对外接口少，或者写完不经常改的可以用这个。Smartdocgitee地址：https://gitee.com/smart-doc-team/smart-doc开源协议：Apache-2.0LicenseStar：758开发语言：html、javascript用户：小米、科大讯飞、1Plus推荐指数：★★★★示例地址：https://gitee.com/smart-doc-team/smart-doc/wikis/documentrendering?sort_id=1652819smart-doc是一个javarestfulapi文档生成工具，smart-doc颠覆了传统类似swagger是一种利用大量注解入侵生成文档的实现方式。smart-doc完全基于接口源码分析生成接口文档，完全实现零注解侵入，只需要按照java标准注释编写即可得到标准的markdown接口文档。优点：基于接口源码分析生成接口文档，零注解侵入，支持html、pdf、markdown格式文件导出。缺点：需要引入额外的jar包，不支持在线调试个人建议：如果是实时生成文档，但又不想添加一些额外的注解，例如：@Api、@ApiModel等注解是必须的使用招摇时，你可以使用这个。Redocgithub地址：https://github.com/Redocly/redoc开源协议：MITLicenseStar：10.7K开发语言：typescript、javascript用户：docker、redocly推荐指数：★★★☆示例地址：https://docs.docker.com/engine/api/v1.40/redoc声称是最好的在线文档工具之一。支持swagger接口数据，提供多种文档生成方式，非常容易部署。使用redoc-cli将您的文档捆绑到具有零依赖性、响应式三面板设计和菜单/滚动同步的HTML文件中。优点：生成文档非常方便，三面板设计缺点：不支持中文搜索，分为：普通版和付费版，普通版不支持在线调试。另外个人觉得UI交互不太适合国内大部分程序员的操作习惯。个人建议：如果想快速搭建一个基于swagger的文档，又不需要在线调试，可以使用这个。knife4jgitee地址：https://gitee.com/xiaoym/knife4j开源协议：Apache-2.0LicenseStar：3k开发语言：java,javascript用户：未知推荐指数：★★★★示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.htmlknife4j是JavaMVC框架集成Swagger生成Api文档的增强方案。它的前身是swagger-bootstrap-ui。kni4j这个名字是希望她能像匕首一样小巧轻便，而且威力强大。优点：基于swagger生成实时在线文档，支持在线调试、全局参数、国际化、访问控制等，功能非常强大。缺点：接口有点丑，需要依赖额外的jar包。个人建议：如果公司对UI要求不高，可以使用这个文档生成工具。比较功能比较强大。yapigithub地址：https://github.com/YMFE/yapi开源协议：Apache-2.0LicenseStar：17.8k开发语言：javascript用户：腾讯、阿里、百度、京东等各大厂商推荐指数：★★★★★示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.htmlyapi由去哪儿前端团队自主开发并开源。主要支持以下功能：可视化界面管理数据mock自动界面测试数据导入（包括swagger、har、postman、json、命令行）权限管理支持本地化部署支持插件支持二次开发优势：非常强大，支持权限管理、在线调试、接口自动化测试、插件开发等非常好。缺点：在线调试功能需要安装插件，用户体检有点差，主要解决跨域问题，可能存在安全问题。不过要解决这个问题，可以自己实现一个插件，应该不难。个人建议：如果不考虑插件安全的安全问题，这款在线文档工具还是非常好用的，可以说是神器，笔者在此强烈推荐。apidocgithub地址：https://github.com/apidoc/apidoc开源协议：MIT授权星级：8.7k开发语言：javascript用户：未知推荐指数：★★★★☆示例地址：https://apidocjs.com/example/#api-Userapidoc是一个简单的RESTfulAPI文档生成工具，它从代码注释中提取格式化内容以生成文档。支持Go、Java、C++、Rust等大部分开发语言，具体可以使用apidoclang命令行查看所有支持列表。apidoc具有以下特点：跨平台，支持linux、windows、macOS等；支持多种语言，即使不支持也很容易扩展；支持多个不同语言的项目生成一个文档；可以自定义输出模板；根据文档生成mock数据；优点：根据代码注释生成在线文档，较少嵌入到代码中，支持多种语言，跨平台，还可以自定义模板。支持搜索和在线调试功能。缺点：需要在注解中添加指定的注解。如果修改了代码参数或类型，则需要同步修改注解的相关内容，需要一定的维护工作量。个人建议：这个在线文档生成工具提供了另一种思路，swagger在代码中添加注解，apidoc在注解中添加数据，代码嵌入较少，推荐使用。showdocgithub地址：https://github.com/star7th/showdoc开源协议：Apache授权星级：8.1k开发语言：javascript、php用户：超过10000+互联网团队在使用推荐指数：★★★★☆示例地址：https://www.showdoc.com.cn/demo?page_id=9ShowDoc是一款非常适合IT团队的在线文档分享工具，可以加快团队之间的沟通效率。它有什么特点：响应式网页设计，项目文件可以分享到电脑或移动设备上查看。同时，项目还可以导出为word文件，供离线浏览。权限管理，ShowDoc上有两类项目：公开项目和私有项目。公共项目可以被任何登录和未登录的用户访问，而私有项目需要输入密码来验证访问。密码由项目创建者设置。ShowDoc使用markdown编辑器，点击编辑器上方的按钮即可轻松插入API接口模板和数据字典模板。ShowDoc为页面提供了历史版本功能，您可以轻松将页面恢复到之前的版本。支持文件导入，文件可以是postman的json文件，swagger的json文件，showdoc的markdown压缩包，系统会自动识别文件类型。优点：支持项目权限管理、多种格式文件导入、全文搜索等功能，使用非常方便。并且它既支持部署自己的服务器，也支持在线托管。缺点：不支持在线调试功能个人建议：如果不需要在线调试功能，这个在线文档工具值得一用。
