smart-doc 是一款同时支持 Java Rest Api 和 Apache Dubbo RPC 接口文档生成的工具，在业内率先提出基于 Java 泛型定义推导的理念，完全基于注释生成文档，做到零侵入。只需要按照Javadoc标准编写注释， smart-doc 就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+ 的文档。

最新版功能

• 零注解、零学习成本、只需要写标准JAVA注释。
• 基于源代码接口定义自动推导，强大的返回结构推导。
• 支持Spring MVC、Spring Boot、Spring Boot Web Flux(Controller书写方式)、Feign。
• 支持Callable、Future、CompletableFuture等异步接口返回的推导。
• 支持JavaBean上的JSR303参数校验规范，包括分组验证。
• 对JSON请求参数的接口能够自动生成模拟JSON参数。
• 对一些常用字段定义能够生成有效的模拟值。
• 支持生成JSON返回值示例。
• 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
• 支持生成多种格式文档：Markdown、HTML5、Word、Asciidoctor、Postman Collection、OpenAPI 3.0。开放文档数据，可自由实现接入文档管理系统。
• 支持导出错误码和定义在代码中的各种字典码到接口文档。
• 支持生成Jmeter性能测试脚本。
• 支持Maven、Gradle插件式轻松集成。
• 支持Apache Dubbo RPC接口文档生成。
• 支持基于Git管理项目的变更增量文档生成。
• debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

🧰 最佳实践方案

smart-doc + Torna 组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档， 自动将文档推送到 Torna 企业级接口文档管理平台。

Torna 是由 smart-doc 官方独家推动联合研发的企业级文档管理系统， 集成 torna 需要使用 smart-doc 2.0.9 版本及以上，目前也是主推 smart-doc+Torna 的这套方案。

如下图所示：

smart-doc和swagger对比

快速体验

smart-doc官方目前已经开发完成 Maven 插件和 Gradle 插件，小编这里使用 Maven 插件按最小化配置举例。

环境版本：

• Maven 3.3.9+
• JDK1.8+

1、在项目启动类所在模块的resources目录下创建 smart-doc.json 文件，内容如下：

{  "outPath": "/path/to/userdir", // 接口文档输出地址 "serverUrl": "http://127.0.0.1:8080"// 请求路径}outPath 可以使用相对路径，如：

./src/main/resources/static/doc2、在项目启动类所在模块的pom.xml文件配置 Maven 插件注意：需要 includes 依赖的源码包

<plugin> <groupId>com.ly.smart-doc</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>[最新版本]</version> <configuration> <configFile>./src/main/resources/smart-doc.json</configFile> <projectName>${project.description}</projectName> <includes> <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 --> <include>com.baomidou:mybatis-plus-extension</include> <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core--> <include>com.baomidou:mybatis-plus-core</include> <!-- 使用了jpa的分页需要include所使用的源码包 --> <include>org.springframework.data:spring-data-commons</include> </includes> </configuration> <executions> <execution> <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉--> <phase>compile</phase> <goals> <!--smart-doc提供了html、openapi、markdown等goal，可按需配置--> <goal>html</goal> </goals> </execution> </executions></plugin>

3、在 IDEA 中直接使用 Maven 插件目录下的 smart-doc 模块