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

時間 2021-04-23

標籤 javascript html 前端 java git 程序員 github docker typescript json 欄目 JavaScript 简体版

原文原文鏈接

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

1.必須是開源的html

2.可以實時生成在線文檔前端

3.支持全文搜索java

4.支持在線調試功能git

5.界面優美程序員

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

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

1、gitbook
github地址：https://github.com/GitbookIO/...typescript

開源協議：Apache-2.0 Licensejson

Star: 22.9k

開發語言：javascript

用戶：50萬+

示例地址：https://www.servicemesher.com...

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

優勢：使用起來很是簡單，支持全文搜索，能夠跟git完美集成，對代碼無任何嵌入性，支持markdown格式的文檔編寫。

缺點：須要單獨維護一個文檔項目，若是接口修改了，須要手動去修改這個文檔項目，否則可能會出現接口和文檔不一致的狀況。而且，不支持在線調試功能。

我的建議：若是對外的接口比較少，或者編寫以後不會常常變更能夠用這個。

2、smartdoc
gitee地址：https://gitee.com/smart-doc-t...

開源協議：Apache-2.0 License

Star: 758

開發語言：html、javascript

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

示例地址：https://gitee.com/smart-doc-t...

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

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

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

我的建議：若是實時生成文檔，可是又不想打一些額外的註解，好比：使用swagger時須要打上@Api、@ApiModel等註解，就可使用這個。

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

開源協議：MIT License

Star: 10.7K

開發語言：typescript、javascript

用戶：docker、redocly

示例地址：https://docs.docker.com/engin...

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

優勢：很是方便生成文檔，三面板設計

缺點：不支持中文搜索，分爲：普通版本和付費版本，普通版本不支持在線調試。另外UI交互我的感受不適合國內大多數程序員的操做習慣。