最近公司打算做一個(gè)openapi開(kāi)放平臺(tái)，讓我找一款好用的在線文檔生成工具脐区，具體要求如下：
1.必須是開(kāi)源的
2.能夠?qū)崟r(shí)生成在線文檔
3.支持全文搜索
4.支持在線調(diào)試功能
5.界面優(yōu)美
說(shuō)實(shí)話绳姨，這個(gè)需求看起來(lái)簡(jiǎn)單登澜，但是實(shí)際上一點(diǎn)的都不簡(jiǎn)單。
我花了幾天時(shí)間到處百度飘庄，谷歌脑蠕，技術(shù)博客 和 論壇查資料，先后調(diào)研了如下文檔生成工具：
一跪削、gitbook
github地址：https://github.com/GitbookIO/gitbook
開(kāi)源協(xié)議：Apache-2.0 License
Star: 22.9k
開(kāi)發(fā)語(yǔ)言：javascript
用戶：50萬(wàn)+
示例地址：https://www.servicemesher.com/envoy/intro/arch_overview/dynamic_configuration.html
GitBook是一款文檔編輯工具。它的功能類似金山WPS中的Word或者微軟Office中的Word的文檔編輯工具切揭。它可以用來(lái)寫(xiě)文檔、建表格锁摔、插圖片廓旬、生成pdf。當(dāng)然谐腰，以上的功能WPS孕豹、Office可能做得更好，但是十气，GitBook還有更最強(qiáng)大的功能：它可以用文檔建立一個(gè)網(wǎng)站励背，讓更多人了解你寫(xiě)的書(shū)，另外砸西，最最核心的是叶眉，他支持Git，也就意味著芹枷，它是一個(gè)分布式的文檔編輯工具衅疙。你可以隨時(shí)隨地來(lái)編寫(xiě)你的文檔，也可以多人共同編寫(xiě)文檔鸳慈，哪怕多人編寫(xiě)同一頁(yè)文檔饱溢，它也能記錄每個(gè)人的內(nèi)容，然后告訴你他們之間的區(qū)別走芋，也能記錄你的每一次改動(dòng)绩郎，你可以查看每一次的書(shū)寫(xiě)記錄和變化潘鲫，哪怕你將文檔都刪除了，它也能找回來(lái)肋杖！這就是它繼承Git后的厲害之處溉仑！
優(yōu)點(diǎn)：使用起來(lái)非常簡(jiǎn)單，支持全文搜索兽愤，可以跟git完美集成彼念，對(duì)代碼無(wú)任何嵌入性，支持markdown格式的文檔編寫(xiě)浅萧。
缺點(diǎn)：需要單獨(dú)維護(hù)一個(gè)文檔項(xiàng)目逐沙，如果接口修改了，需要手動(dòng)去修改這個(gè)文檔項(xiàng)目洼畅，不然可能會(huì)出現(xiàn)接口和文檔不一致的情況吩案。并且，不支持在線調(diào)試功能帝簇。
個(gè)人建議：如果對(duì)外的接口比較少徘郭，或者編寫(xiě)之后不會(huì)經(jīng)常變動(dòng)可以用這個(gè)。
二丧肴、smartdoc
gitee地址：https://gitee.com/smart-doc-team/smart-doc
開(kāi)源協(xié)議：Apache-2.0 License
Star: 758
開(kāi)發(fā)語(yǔ)言：html残揉、javascript
用戶：小米、科大訊飛芋浮、1加
示例地址：https://gitee.com/smart-doc-team/smart-doc/wikis/文檔效果圖?sort_id=1652819
smart-doc是一個(gè)java restful api文檔生成工具，smart-doc顛覆了傳統(tǒng)類似swagger這種大量采用注解侵入來(lái)生成文檔的實(shí)現(xiàn)方法纸巷。smart-doc完全基于接口源碼分析來(lái)生成接口文檔镇草，完全做到零注解侵入，只需要按照java標(biāo)準(zhǔn)注釋的寫(xiě)就能得到一個(gè)標(biāo)準(zhǔn)的markdown接口文檔瘤旨。
優(yōu)點(diǎn)：基于接口源碼分析生成接口文檔梯啤，零注解侵入，支持html存哲、pdf因宇、markdown格式的文件導(dǎo)出。
缺點(diǎn)：需要引入額外的jar包祟偷，不支持在線調(diào)試
個(gè)人建議：如果實(shí)時(shí)生成文檔羽嫡，但是又不想打一些額外的注解，比如：使用swagger時(shí)需要打上@Api肩袍、@ApiModel等注解杭棵，就可以使用這個(gè)。
三、redoc
github地址：https://github.com/Redocly/redoc
開(kāi)源協(xié)議：MIT License
Star: 10.7K
開(kāi)發(fā)語(yǔ)言：typescript魂爪、javascript
用戶：docker先舷、redocly
示例地址：https://docs.docker.com/engine/api/v1.40/
redoc自己號(hào)稱是一個(gè)最好的在線文檔工具滓侍。它支持swagger接口數(shù)據(jù)蒋川，提供了多種生成文檔的方式，非常容易部署撩笆。使用redoc-cli能夠?qū)⒛奈臋n捆綁到零依賴的 HTML文件中捺球，響應(yīng)式三面板設(shè)計(jì)，具有菜單/滾動(dòng)同步夕冲。
優(yōu)點(diǎn)：非常方便生成文檔氮兵，三面板設(shè)計(jì)
缺點(diǎn)：不支持中文搜索，分為：普通版本 和 付費(fèi)版本歹鱼，普通版本不支持在線調(diào)試泣栈。另外UI交互個(gè)人感覺(jué)不適合國(guó)內(nèi)大多數(shù)程序員的操作習(xí)慣。
個(gè)人建議：如果想快速搭建一個(gè)基于swagger的文檔弥姻，并且不要求在線調(diào)試功能南片，可以使用這個(gè)。
四庭敦、knife4j
gitee地址：https://gitee.com/xiaoym/knife4j
開(kāi)源協(xié)議：Apache-2.0 License
Star: 3k
開(kāi)發(fā)語(yǔ)言：java疼进、javascript
用戶：未知
示例地址：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í)時(shí)在線文檔伞广，支持在線調(diào)試，全局參數(shù)定血、國(guó)際化、訪問(wèn)權(quán)限控制等诞外，功能非常強(qiáng)大澜沟。
缺點(diǎn)：界面有一點(diǎn)點(diǎn)丑，需要依賴額外的jar包
個(gè)人建議：如果公司對(duì)ui要求不太高峡谊，可以使用這個(gè)文檔生成工具茫虽，比較功能還是比較強(qiáng)大的。
五既们、yapi
github地址：https://github.com/YMFE/yapi
開(kāi)源協(xié)議：Apache-2.0 License
Star: 17.8k
開(kāi)發(fā)語(yǔ)言：javascript
用戶：騰訊濒析、阿里、美團(tuán)啥纸、百度号杏、京東等大廠
示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
yapi是去哪兒前端團(tuán)隊(duì)自主研發(fā)并開(kāi)源的，主要支持以下功能：
- 可視化接口管理
- 數(shù)據(jù)mock
- 自動(dòng)化接口測(cè)試
- 數(shù)據(jù)導(dǎo)入（各種盾致，包括swagger主经、har、postman庭惜、json罩驻、命令行）
- 權(quán)限管理
- 支持本地化部署
- 支持插件
- 支持二次開(kāi)發(fā)
優(yōu)點(diǎn)：功能非常強(qiáng)大，支持權(quán)限管理护赊、在線調(diào)試惠遏、接口自動(dòng)化測(cè)試、插件開(kāi)發(fā)等骏啰，BAT等大廠等在使用节吮，說(shuō)明功能很好。
缺點(diǎn)：在線調(diào)試功能需要安裝插件器一，用戶體檢稍微有點(diǎn)不好课锌，主要是為了解決跨域問(wèn)題，可能有安全性問(wèn)題祈秕。不過(guò)要解決這個(gè)問(wèn)題渺贤，可以自己實(shí)現(xiàn)一個(gè)插件，應(yīng)該不難请毛。
個(gè)人建議：如果不考慮插件安全的安全性問(wèn)題志鞍，這個(gè)在線文檔工具還是非常好用的，可以說(shuō)是一個(gè)神器方仿，筆者在這里強(qiáng)烈推薦一下固棚。
看完三件事??
如果你覺(jué)得這篇內(nèi)容對(duì)你還蠻有幫助，我想邀請(qǐng)你幫我三個(gè)小忙：
點(diǎn)贊仙蚜，轉(zhuǎn)發(fā)此洲，有你們的 『點(diǎn)贊和評(píng)論』，才是我創(chuàng)造的動(dòng)力委粉。
關(guān)注公眾號(hào) 『 Java斗帝 』呜师，不定期分享原創(chuàng)知識(shí)。
同時(shí)可以期待后續(xù)文章ing??
