求你別再用Swagger了，給你推薦幾個在線文檔生成神器
前言
最近公司打算做一個openapi開放平臺，讓我找一款好用的在線文檔生成工具，具體要求如下：
- 必須是開源的
- 能夠?qū)崟r生成在線文檔
- 支持全文搜索
- 支持在線調(diào)試功能
- 界
- 面優(yōu)美
說實(shí)話，這個需求看起來簡單，但是實(shí)際上一點(diǎn)的都不簡單。
我花了幾天時間到處查資料，先后調(diào)研了如下文檔生成工具：
gitbookgithub
地址：https://github.com/GitbookIO/gitbook
開源協(xié)議：Apache-2.0 License
Star: 22.9k
開發(fā)語言：javascript
用戶：50萬+
推薦指數(shù)：★★★
示例地址：https://www.servicemesher.com/envoy/intro/arch_overview/dynamic_configuration.html
gitBook是一款文檔編輯工具。它的功能類似金山WPS中的word或者微軟office中的word的文檔編輯工具。它可以用來寫文檔、建表格、插圖片、生成pdf。當(dāng)然，以上的功能WPS、office可能做得更好，但是，gitBook還有更最強(qiáng)大的功能：它可以用文檔建立一個網(wǎng)站，讓更多人了解你寫的書，另外，最最核心的是，他支持Git，也就意味著，它是一個分布式的文檔編輯工具。你可以隨時隨地來編寫你的文檔，也可以多人共同編寫文檔，哪怕多人編寫同一頁文檔，它也能記錄每個人的內(nèi)容，然后告訴你他們之間的區(qū)別，也能記錄你的每一次改動，你可以查看每一次的書寫記錄和變化，哪怕你將文檔都刪除了，它也能找回來!這就是它繼承g(shù)it后的厲害之處!
優(yōu)點(diǎn)：使用起來非常簡單，支持全文搜索，可以跟git完美集成，對代碼無任何嵌入性，支持markdown格式的文檔編寫。
缺點(diǎn)：需要單獨(dú)維護(hù)一個文檔項(xiàng)目，如果接口修改了，需要手動去修改這個文檔項(xiàng)目，不然可能會出現(xiàn)接口和文檔不一致的情況。并且，不支持在線調(diào)試功能。
個人建議：如果對外的接口比較少，或者編寫之后不會經(jīng)常變動可以用這個。
smartdoc
gitee地址：https://gitee.com/smart-doc-team/smart-doc
開源協(xié)議：Apache-2.0 License
Star: 758
開發(fā)語言：html、javascript
用戶：小米、科大訊飛、1加
推薦指數(shù)：★★★★
示例地址：https://gitee.com/smart-doc-team/smart-doc/wikis/文檔效果圖?sort_id=1652819
smart-doc是一個java restful api文檔生成工具，smart-doc顛覆了傳統(tǒng)類似swagger這種大量采用注解侵入來生成文檔的實(shí)現(xiàn)方法。smart-doc完全基于接口源碼分析來生成接口文檔，完全做到零注解侵入，只需要按照java標(biāo)準(zhǔn)注釋的寫就能得到一個標(biāo)準(zhǔn)的markdown接口文檔。
優(yōu)點(diǎn)：基于接口源碼分析生成接口文檔，零注解侵入，支持html、pdf、markdown格式的文件導(dǎo)出。
缺點(diǎn)：需要引入額外的jar包，不支持在線調(diào)試
個人建議：如果實(shí)時生成文檔，但是又不想打一些額外的注解，比如：使用swagger時需要打上@Api、@ApiModel等注解，就可以使用這個。
redoc
github地址：https://github.com/Redocly/redoc
開源協(xié)議：MIT License
Star: 10.7K
開發(fā)語言：typescript、javascript
用戶：docker、redocly
推薦指數(shù)：★★★☆
示例地址：https://docs.docker.com/engine/api/v1.40/
redoc自己號稱是一個最好的在線文檔工具。它支持swagger接口數(shù)據(jù)，提供了多種生成文檔的方式，非常容易部署。使用redoc-cli能夠?qū)⒛奈臋n捆綁到零依賴的 HTML文件中，響應(yīng)式三面板設(shè)計，具有菜單/滾動同步。
優(yōu)點(diǎn)：非常方便生成文檔，三面板設(shè)計
缺點(diǎn)：不支持中文搜索，分為：普通版本 和 付費(fèi)版本，普通版本不支持在線調(diào)試。另外UI交互個人感覺不適合國內(nèi)大多數(shù)程序員的操作習(xí)慣。
個人建議：如果想快速搭建一個基于swagger的文檔，并且不要求在線調(diào)試功能，可以使用這個。
knife4j
gitee地址：https://gitee.com/xiaoym/knife4j
開源協(xié)議：Apache-2.0 License
Star: 3k
開發(fā)語言：java、javascript
用戶：未知
推薦指數(shù)：★★★★
示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
knife4j是為Java MVC框架集成Swagger生成Api文檔的增強(qiáng)解決方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一樣小巧,輕量,并且功能強(qiáng)悍。
優(yōu)點(diǎn)：基于swagger生成實(shí)時在線文檔，支持在線調(diào)試，全局參數(shù)、國際化、訪問權(quán)限控制等，功能非常強(qiáng)大。
缺點(diǎn)：界面有一點(diǎn)點(diǎn)丑，需要依賴額外的jar包
個人建議：如果公司對ui要求不太高，可以使用這個文檔生成工具，比較功能還是比較強(qiáng)大的。
yapi
github地址：https://github.com/YMFE/yapi
開源協(xié)議：Apache-2.0 License
Star: 17.8k
開發(fā)語言：javascript
用戶：騰訊、阿里、百度、京東等大廠
推薦指數(shù)：★★★★★
示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
yapi是去哪兒前端團(tuán)隊自主研發(fā)并開源的，主要支持以下功能：
- 可視化接口管理
- 數(shù)據(jù)mock
- 自動化接口測試
- 數(shù)據(jù)導(dǎo)入(包括swagger、har、postman、json、命令行)
- 權(quán)限管理
- 支持本地化部署
- 支持插件
- 支持二次開發(fā)
優(yōu)點(diǎn)：功能非常強(qiáng)大，支持權(quán)限管理、在線調(diào)試、接口自動化測試、插件開發(fā)等，BAT等大廠等在使用，說明功能很好。
缺點(diǎn)：在線調(diào)試功能需要安裝插件，用戶體檢稍微有點(diǎn)不好，主要是為了解決跨域問題，可能有安全性問題。不過要解決這個問題，可以自己實(shí)現(xiàn)一個插件，應(yīng)該不難。
個人建議：如果不考慮插件安全的安全性問題，這個在線文檔工具還是非常好用的，可以說是一個神器，筆者在這里強(qiáng)烈推薦一下。
apidoc
github地址：https://github.com/apidoc/apidoc
開源協(xié)議：MIT License
Star: 8.7k
開發(fā)語言：javascript
用戶：未知
推薦指數(shù)：★★★★☆
示例地址：https://apidocjs.com/example/#api-User
apidoc 是一個簡單的 RESTful API 文檔生成工具，它從代碼注釋中提取特定格式的內(nèi)容生成文檔。支持諸如 Go、Java、C++、Rust 等大部分開發(fā)語言，具體可使用 apidoc lang 命令行查看所有的支持列表。
apidoc 擁有以下特點(diǎn)：
- 跨平臺，linux、windows、macOS 等都支持;
- 支持語言廣泛，即使是不支持，也很方便擴(kuò)展;
- 支持多個不同語言的多個項(xiàng)目生成一份文檔;
- 輸出模板可自定義;
- 根據(jù)文檔生成 mock 數(shù)據(jù);
優(yōu)點(diǎn)：基于代碼注釋生成在線文檔，對代碼的嵌入性比較小，支持多種語言，跨平臺，也可自定義模板。支持搜索和在線調(diào)試功能。
缺點(diǎn)：需要在注釋中增加指定注解，如果代碼參數(shù)或類型有修改，需要同步修改注解相關(guān)內(nèi)容，有一定的維護(hù)工作量。
個人建議：這種在線文檔生成工具提供了另外一種思路，swagger是在代碼中加注解，而apidoc是在注解中加數(shù)據(jù)，代碼嵌入性更小，推薦使用。
showdoc
github地址：https://github.com/star7th/showdoc
開源協(xié)議：Apache Licence
Star: 8.1k
開發(fā)語言：javascript、php
用戶：超過10000+互聯(lián)網(wǎng)團(tuán)隊正在使用
推薦指數(shù)：★★★★☆
示例地址：https://www.showdoc.com.cn/demo?page_id=9
ShowDoc就是一個非常適合IT團(tuán)隊的在線文檔分享工具，它可以加快團(tuán)隊之間溝通的效率。
它都有些什么功能：
- 響應(yīng)式網(wǎng)頁設(shè)計，可將項(xiàng)目文檔分享到電腦或移動設(shè)備查看。同時也可以將項(xiàng)目導(dǎo)出成word文件，以便離線瀏覽。
- 權(quán)限管理，ShowDoc上的項(xiàng)目有公開項(xiàng)目和私密項(xiàng)目兩種。公開項(xiàng)目可供任何登錄與非登錄的用戶訪問，而私密項(xiàng)目則需要輸入密碼驗(yàn)證訪問。密碼由項(xiàng)目創(chuàng)建者設(shè)置。
- ShowDoc采用markdown編輯器，點(diǎn)擊編輯器上方的按鈕可方便地插入API接口模板和數(shù)據(jù)字典模板。
- ShowDoc為頁面提供歷史版本功能，你可以方便地把頁面恢復(fù)到之前的版本。
- 支持文件導(dǎo)入，文件可以是postman的json文件、swagger的json文件、showdoc的markdown壓縮包，系統(tǒng)會自動識別文件類型。
優(yōu)點(diǎn)：支持項(xiàng)目權(quán)限管理，多種格式文件導(dǎo)入，全文搜索等功能，使用起來還是非常方便的。并且既支持部署自己的服務(wù)器，也支持在線托管兩種方式。
缺點(diǎn)：不支持在線調(diào)試功能
個人建議：如果不要求在線調(diào)試功能，這個在線文檔工具值得使用。
