smart-doc Java 零侵入 API 文档生成 2.7.0 发布

[smartdoc647]

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，smart-doc 利用接口泛型和 javadoc 注释自动分析生成 api 接口文档，不采用任何注解侵入到业务代码中。只需要在项目中引入 smart-doc 提供的 maven 或者是 gradle 插件，然后按照规范写好 javadoc 注释即可生成 api 文档。同时 smart-doc 也支持生成 openapi 和 postman 这些规范的文档，生成后可以直接导入相关工具做测试。

仓库地址

https://github.com/smart-doc-group/smart-doc

Features

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

更新内容

1. 支持在子类使用 @JsonIgnore 忽略后，同时忽略父类中的同名字段，#509
2. 修复内部类嵌套结构 formdata example 错误。pr#512
3. 修复 url 中使用环境变量表达式时解析错误，#515

发展情况

smart-doc 开源维护接近五年，目前很多功能已经非常稳定，国内有很多的用户。码云 star 3k+，github star 1k+ 。smart-doc 官方布道的企业级文档管理系统 torna 的 docker 镜像下载量超过 10k 。国内已有数家知名司在使用 smart-doc ，如：科大讯飞、小米、一加、顺丰、马蜂窝、同程旅行等。smart-doc+torna 的整套 API 管理体系已经被很多公司落地使用。

[zgcwkj]

和 Swagger 比，有什么优势？

[Dlin]

@zgcwkj 人家写了嘛，无侵入

[pigf]

好用，在用，支持

[yifeng33]

我们组好像准备用这个，让我完善 java doc

[Masoud2023]

真要怕侵入应该连这个也不要用直接手写 openapi ，都写 java 这么啰嗦的东西了，写几行 swagger 注解我觉得也没什么。

[smartdoc647]

@Masoud2023 真没几个人愿意手写文档，或者 openapi 这种结构化文档的，没必要把时候花费在这种对技术毫无增长的东西上，工具的目的是提升效率替代简单的工作。swagger 在中小公司还好，大厂基本用不起来，不要问我怎么知道的，毕竟我因为开源和阿里、蚂蚁、字节、华为都有接触。还有是不要有什么语言偏向性，大佬都是多语言并行的，像我这种菜狗也是 java 和 golang 主力开发并行，两个语言也都有开源贡献。我身边搞 java 的同事拿着 apache commiter 简直香的不行，走到哪里圈子里都会尊敬。

[LeegoYih]

👍🏻提供另一种解决方案

[iminto]

我直接 javadoc ，这才是真的零侵入，不需要导包。

javadoc 不支持的注解，还能用 tag 进行扩展。

[zhangwugui]

支持，项目中已经使用，已本地化部署

[jamel]

支持 grpc-spring-boot-starter 不

[alteremliu]

已经在使用了，好评

[smartdoc647]

@iminto 可以分享下解决方案，如果 javadoc 完整解决 rest 业务接口的文档其实挺好的，但是我的了解是类嵌套这种肯定 javadoc 不行，工具的目的还是在于让程序员把事情做好的同时，少写点东西，所以 smart-doc 就是能自动解析的都给自动解析，

[tudou527]

我来提供一个基于 javadoc 的方案： https://oneapi.app （支付宝内部方案的开源版本）

[totoro52]

看看，不喜欢 sw 的牛皮癣一样存在的注解

[smartdoc647]

@tudou527 你们这个思路也可以，非常棒，主要是可以不改项目。这也是我之前想改造的方式。你们其实可以做些宣传，把 case 补起来。小公司的代码 case 是比较多的，大厂规范度相对高点。不过这类工具未来其实是可以用大模型训练去取代的，生成 api 这个完全可以训练出来。

[iminto]

@smartdoc647

javadoc 原生支持 param,link 这些注解，但是对于 restful 的接口，还需要譬如 method ，path 这些参数，javadoc 支持 tag/taglet 这些扩展语法，能让生产的文档可读性更加。

我啥都没弄，就是扩展了下 javadoc 的注解，让它生成的文档更像那么回事

[WashFreshFresh]

挺好的，可惜我司项目不支持，统一入口，通过参数反射调用不同 service 的不同 method 当 controller...

[misaka19000]

最近在用 qdox 解析源码，用的就是作者大大发布的 maven 版本，居然在这里看到了原作者了~~~蹭蹭😁

[smartdoc647]

@jamel grpc 不支持，但是欢迎参与共建