思否開源項目推介丨smart-doc：爲 java 開發人員打造的零侵入接口文檔生成工具

時間 2020-11-01

標籤 git github segmentfault 後端架構異步 maven 微服務工具源碼分析欄目 Java 简体版

原文原文鏈接

開源項⽬名稱： smart-doc
開源項⽬負責⼈： 上官胡鬧
開源項⽬簡介： smart-doc 是一款同時支持 JAVA RESTFUL API 和 Apache Dubbo RPC 零侵入接口文檔生成的工具
開源項⽬類型： 我的
項⽬建立時間： 2018 年 8 ⽉23 ⽇
GitHub 數據： 301 Star，69 Fork
GitHub 地址： https://github.com/smart-doc-group/smart-doc

項⽬介紹

smart-doc 是一款同時支持 JAVA RESTFUL API 和 Apache Dubbo RPC 接口文檔生成的工具，smart-doc 顛覆了傳統相似swagger這種大量採用註解侵入來生成文檔的實現方法。 smart-doc 徹底基於接口源碼分析來生成接口文檔，徹底作到零註解侵入，用戶只須要按照 Java 標準註釋編寫，smart-doc 就能掃描源代碼生成一個簡易明瞭的 Markdown 或靜態 HTML5 文檔，同時 smart-doc 在分析接口定義代碼時一直遵循規範至上的理念，一些不規範的寫法 smart-doc 毫不支持，使得技術團隊在引入 smart-doc 能搞很好的保持團隊的代碼統一性。git

Features

零註解、零學習成本、只須要寫標準 Java 註釋。
基於源代碼接口定義自動推導，強大的返回結構推導。
支持 Spring MVC、Spring Boot、Spring Boot Web Flux(controller書寫方式)、Feign。
支持 Callable、Future、CompletableFuture 等異步接口返回的推導。
支持 JavaBean上的JSR303 參數校驗規範，包括分組驗證。
對 JSON 請求參數的接口可以自動生成模擬 JSON 參數。
對一些經常使用字段定義可以生成有效的模擬值。
支持生成 JSON 返回值示例。
支持從項目外部加載源代碼來生成字段註釋(包括標準規範發佈的jar包)。
支持生成多種格式文檔：Markdown、HTML五、Asciidoctor、Postman Collection v2.0。
輕易實如今 Spring Boot 服務上在線查看靜態HTML5 API 文檔。
開放文檔數據，可自由實現接入文檔管理系統。
支持導出錯誤碼和定義在代碼中的各類字典碼到接口文檔。
支持 maven、Gradle 插件式輕鬆集成。
支持 Apache Dubbo RPC 接口文檔生成。

smart-doc 輔助插件

smart-doc 官方目前已經開發完成maven插件和 Gradle 插件。經過插件能夠更快快速的將 smart-doc 引入到本身的項目中去實現接口文檔生成。github

maven插件：https://github.com/smart-doc-group/smart-doc-maven-plugin
gradle插件：https://github.com/smart-doc-group/smart-doc-gradle-pluginsegmentfault

團隊介紹

上官胡鬧，smart-doc 發起人，因看一眼 swagge r不爽而發起 smart-doc 開源，擁有 6 年的軟件開發經驗，在大中型和創業型公司都工做過，比較瞭解不一樣類型公司的研發體系。目前就任於科大訊飛負責主導團隊項目的微服務和容器化架構。後端

xingzi，西南科技大學信息工程學院碩士研究生在讀，smart-doc 項目核心貢獻者，熱愛開源。架構

宋浩志，smart-doc項目核心貢獻者，杭州某公司後端核心開發，熱愛開源。異步

項目自薦

smart-doc 開源近兩年來，在開源社區得到了國內不少開發人員的讚揚，也得到了不少企業技術團隊的確定。根據社區的反應看國內採用 smart-doc 來生成文檔的公司超過 100 家，包括像一加、科大訊飛、小米這些知名業務內部都有部分 Java 開發技術團隊在使用smart-doc。maven

smart-doc 在社區的驅動下已經逐步完善，支持的功能愈來愈多。咱們但願可以把 smart-doc 推薦給給更多不喜歡強侵入性文檔工具的開發人員，幫助他們更快速的去構建本身的接口文檔。微服務

後續咱們仍將堅持初心，不斷完善和打磨工具，爲開發者賦能，幫助你們更加便捷的去構建友好的接口文檔，提升技術團隊的效率。工具

該項目已入選「SFOSSP - 思否開源項目支持計劃」，咱們但願藉助社區的資源對開源項目進行相關的宣傳推廣，並做爲一個長期項目助力開源事業的發展，與廣大開發者共建開源新生態。
有意向的開源項目負責人或團隊成員，可經過郵箱（pr@segmentfault.com）提供相應的信息（開源項目地址、項目介紹、團隊介紹、聯繫方式等），以便提高交流的效率。