思否开源项目推介丨smart-doc：为 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 能搞很好的保持团队的代码统一性。

Features

• 零注解、零学习成本、只需要写标准 Java 注释。
• 基于源代码接口定义自动推导，强大的返回结构推导。
• 支持 Spring MVC、Spring Boot、Spring Boot Web Flux(controller书写方式)、Feign。
• 支持 Callable、Future、CompletableFuture 等异步接口返回的推导。
• 支持 JavaBean上的JSR303 参数校验规范，包括分组验证。
• 对 JSON 请求参数的接口能够自动生成模拟 JSON 参数。
• 对一些常用字段定义能够生成有效的模拟值。
• 支持生成 JSON 返回值示例。
• 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
• 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection v2.0。
• 轻易实现在 Spring Boot 服务上在线查看静态HTML5 API 文档。
• 开放文档数据，可自由实现接入文档管理系统。
• 支持导出错误码和定义在代码中的各种字典码到接口文档。
• 支持 maven、Gradle 插件式轻松集成。
• 支持 Apache Dubbo RPC 接口文档生成。

smart-doc 辅助插件

smart-doc 官方目前已经开发完成maven插件 和 Gradle 插件。通过插件可以更快快速的将 smart-doc 引入到自己的项目中去实现接口文档生成。

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

团队介绍

上官胡闹，smart-doc 发起人，因看一眼 swagge r不爽而发起 smart-doc 开源，拥有 6 年的软件开发经验，在大中型和创业型公司都工作过，比较了解不同类型公司的研发体系。目前就职于科大讯飞负责主导团队项目的微服务和容器化架构。

xingzi，西南科技大学信息工程学院硕士研究生在读，smart-doc 项目核心贡献者，热爱开源。

宋浩志，smart-doc项目核心贡献者，杭州某公司后端核心开发，热爱开源。

项目自荐

smart-doc 开源近两年来，在开源社区获得了国内很多开发人员的赞赏，也获得了很多企业技术团队的肯定。根据社区的反应看国内采用 smart-doc 来生成文档的公司超过 100 家，包括像一加、科大讯飞、小米这些知名业务内部都有部分 Java 开发技术团队在使用smart-doc。

smart-doc 在社区的驱动下已经逐步完善，支持的功能越来越多。我们希望能够把 smart-doc 推荐给给更多不喜欢强侵入性文档工具的开发人员，帮助他们更快速的去构建自己的接口文档。

后续我们仍将坚持初心，不断完善和打磨工具，为开发者赋能，帮助大家更加便捷的去构建友好的接口文档，提高技术团队的效率。

该项目已入选「SFOSSP - 思否开源项目支持计划」，我们希望借助社区的资源对开源项目进行相关的宣传推广，并作为一个长期项目助力开源事业的发展，与广大开发者共建开源新生态。
有意向的开源项目负责人或团队成员，可通过邮箱（[e-mail]）提供相应的信息（开源项目地址、项目介绍、团队介绍、联系方式等），以便提升交流的效率。