別再用swagger了，給你推薦幾個文檔生成神器

最近公司打算做一個openapi開放平臺，讓我找一款好用的在線文檔生成工具，具體要求如下：

1.必須是開源的

2.能夠實時生成在線文檔

3.支持全文搜索

4.支持在線調試功能

5.界面優美

說實話，這個需求看起來簡單，但是實際上一點的都不簡單。

我花了幾天時間到處百度，谷歌，技術博客 和 論壇查資料，先後調研了如下文檔生成工具：

一、Gitbook

github地址：https://github.com/GitbookIO/gitbook

開源協議：Apache-2.0 License

Star: 22.9k

開發語言：javascript

用戶：50萬+

示例地址：https://www.servicemesher.com/envoy/intro/arch_overview/dynamic_configuration.html

GitBook是一款文檔編輯工具。它的功能類似金山WPS中的Word或者微軟Office中的Word的文檔編輯工具。它可以用來寫文檔、建表格、插圖片、生成pdf。當然，以上的功能WPS、Office可能做得更好，但是，GitBook還有更最強大的功能：它可以用文檔建立一個網站，讓更多人了解你寫的書，另外，最最核心的是，他支持Git，也就意味著，它是一個分布式的文檔編輯工具。你可以隨時隨地來編寫你的文檔，也可以多人共同編寫文檔，哪怕多人編寫同一頁文檔，它也能記錄每個人的內容，然後告訴你他們之間的區別，也能記錄你的每一次改動，你可以查看每一次的書寫記錄和變化，哪怕你將文檔都刪除了，它也能找回來！這就是它繼承Git後的厲害之處！

優點：使用起來非常簡單，支持全文搜索，可以跟git完美集成，對代碼無任何嵌入性，支持markdown格式的文檔編寫。

缺點：需要單獨維護一個文檔項目，如果接口修改了，需要手動去修改這個文檔項目，不然可能會出現接口和文檔不一致的情況。並且，不支持在線調試功能。

個人建議：如果對外的接口比較少，或者編寫之後不會經常變動可以用這個。

二、smartdoc

gitee地址：https://gitee.com/smart-doc-team/smart-doc

開源協議：Apache-2.0 License

Star: 758

開發語言：html、javascript

用戶：小米、科大訊飛、1加

示例地址：https://gitee.com/smart-doc-team/smart-doc/wikis/文檔效果圖?sort_id=1652819

smart-doc是一個java restful api文檔生成工具，smart-doc顛覆了傳統類似swagger這種大量採用註解侵入來生成文檔的實現方法。smart-doc完全基於接口源碼分析來生成接口文檔，完全做到零註解侵入，只需要按照java標準注釋的寫就能得到一個標準的markdown接口文檔。

優點：基於接口源碼分析生成接口文檔，零註解侵入，支持html、pdf、markdown格式的文件導出。

缺點：需要引入額外的jar包，不支持在線調試

個人建議：如果實時生成文檔，但是又不想打一些額外的註解，比如：使用swagger時需要打上@Api、@ApiModel等註解，就可以使用這個。

三、redoc

github地址：https://github.com/Redocly/redoc

開源協議：MIT License

Star: 10.7K

開發語言：typescript、javascript

用戶：docker、redocly

示例地址：https://docs.docker.com/engine/api/v1.40/

redoc自己號稱是一個最好的在線文檔工具。它支持swagger接口數據，提供了多種生成文檔的方式，非常容易部署。使用redoc-cli能夠將您的文檔捆綁到零依賴的 HTML文件中，響應式三面板設計，具有菜單/滾動同步。

優點：非常方便生成文檔，三面板設計

缺點：不支持中文搜索，分為：普通版本 和 付費版本，普通版本不支持在線調試。另外UI交互個人感覺不適合國內大多數程式設計師的操作習慣。

個人建議：如果想快速搭建一個基於swagger的文檔，並且不要求在線調試功能，可以使用這個。

四、knife4j

gitee地址：https://gitee.com/xiaoym/knife4j

開源協議：Apache-2.0 License

Star: 3k

開發語言：java、javascript

用戶：未知

示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

knife4j是為Java MVC框架集成Swagger生成Api文檔的增強解決方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一樣小巧,輕量,並且功能強悍。

優點：基於swagger生成實時在線文檔，支持在線調試，全局參數、國際化、訪問權限控制等，功能非常強大。

缺點：界面有一點點醜，需要依賴額外的jar包

個人建議：如果公司對ui要求不太高，可以使用這個文檔生成工具，比較功能還是比較強大的。

五、yapi

github地址：https://github.com/YMFE/yapi

開源協議：Apache-2.0 License

Star: 17.8k

開發語言：javascript

用戶：騰訊、阿里、美團、百度、京東等大廠

示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

yapi是去哪兒前端團隊自主研發並開源的，主要支持以下功能：

• 可視化接口管理
• 數據mock
• 自動化接口測試
• 數據導入（各種，包括swagger、har、postman、json、命令行）
• 權限管理
• 支持本地化部署
• 支持插件
• 支持二次開發

優點：功能非常強大，支持權限管理、在線調試、接口自動化測試、插件開發等，BAT等大廠等在使用，說明功能很好。

缺點：在線調試功能需要安裝插件，用戶體檢稍微有點不好，主要是為了解決跨域問題，可能有安全性問題。不過要解決這個問題，可以自己實現一個插件，應該不難。

個人建議：如果不考慮插件安全的安全性問題，這個在線文檔工具還是非常好用的，可以說是一個神器，筆者在這裡強烈推薦一下。

如果這篇文檔對您有所幫助的話，麻煩關注一下我的公眾帳號：蘇三說技術，或者幫忙點讚或轉發，堅持原創不易，您的支持是我堅持最大的動力。後面我會分享更多更實用的乾貨，謝謝大家的支持。