smart-doc 是一個 java restful api 文檔生成工具,smart-doc 顛覆了傳統類似 swagger 這種大量採用註解侵入來生成文檔的實現方法。 smart-doc 完全基於介面源碼分析來生成介面文檔,完全做到零註解侵入,你只需要按照java標準註釋的寫,smart-doc 就能幫你生成一個簡易明了的 Markdown、Html、AsciiDoc 文檔。
如果你已經厭倦了 swagger 等文檔工具的無數註解和強侵入污染,那請擁抱 smart-doc吧!喜歡 smart-doc 的用戶也不要忘記給項目 star,你們的支持是 smart-doc 持續推進的動力。
功能特性
- 零註解、零學習成本、只需要寫標準java註釋。
- 基於源代碼介面定義自動推導,強大的返回結構推導。
- 支持 Spring MVC、Spring Boot、Spring Boot Web Flux(controller 書寫方式)。
- 支持 Callable、Future、CompletableFuture 等非同步介面返回的推導。
- 支持 JavaBean 上的 JSR303 參數校驗規範。
- 對 json 請求參數的介面能夠自動生成模擬 json 參數。
- 對一些常用欄位定義能夠生成有效的模擬值。
- 支持生成 json 返回值示例。
- 支持從項目外部載入源代碼來生成欄位註釋(包括標準規範發布的 jar 包)。
- 支持生成多種格式文檔:Markdown、HTML5、Asciidoctor。
- 輕易實現在 Spring Boot 服務上在線查看靜態 HTML5 api 文檔。
- 開放文檔數據,可自由實現接入文檔管理系統。
- 一款代碼註釋檢測工具,不寫註釋的小夥伴逃不過法眼了。
- 支持導出錯誤碼和定義在代碼中的各種枚舉字典到介面文檔。
Smart-doc vs Swagger
- smart-doc 不是對 Swagger 造輪子,這是一款用完全不同的理念重新開發的 restful api 介面文檔生成工具。
- smart-doc 比 swagger 集成更簡單,可以自由生成多種格式的 api 文檔。
- smart-doc 完全不需要在侵入到業務代碼中寫任何註解,複雜嵌套對象自動推導出定義欄位結構。
- smart-doc 代碼量很少,如果不能滿足你的需求完全可以自己修改源碼定製(當前有數十家企業基於smart-doc強大的源碼分析能力做二次修改內部使用)。
更新內容
- 修改timestamp類型欄位創建json示例錯誤bug。
- fix #I1545A 單介面多路徑bug。
- 修改部分url生成部署空格問題。
- 優化對java.util.concurrent.ConcurrentMap的解析。
DEMO
使用 demo 只有smart-doc能夠自己分析出完善文檔的demo
相關文檔
- 關於 java web restful api 文檔的重新探索
- smart-doc 功能使用介紹
- 項目官方 wiki
用戶評價
部分使用者對 smart-doc 的評價
- 最強大的 doc 組件,強制要求了規範,也不會污染代碼,欣喜之情溢於言表!
- smartdoc 從註釋入手,即規範強化了文檔的編寫又能提供源碼文檔之外的 api 功能,真的對得起 smart 的稱謂。
Smart-doc用戶
很多人看到smart-doc會問,有人用嗎?目前有數十家企業因為代碼風格和自定義註解問題不能滿足,他們基於smart-doc做定製修改內部使用。有幾十家企業直接使用smart-doc生成內部介面對接文檔。我們最近的新版本發布修復的bug都來自用戶的反饋,這些反饋信息來自技術交流群、issues和郵件。很多用戶之所以選擇smart-doc,不是因為smart-doc做的有多好,而是其它工具要麼侵入性強,要麼源碼解析能力太弱無法分析大多數公司的源代碼給出可用的文檔。