smart-doc Java 零侵入 API 文档生成 2.7.0 发布
smartdoc647 · 2023-06-12 10:07:41 +08:00 · 2022 次点击这是一个创建于 564 天前的主题，其中的信息可能已经有所发展或是发生改变。
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 接口文档生成。
更新内容
- 支持在子类使用 @JsonIgnore 忽略后，同时忽略父类中的同名字段，#509
- 修复内部类嵌套结构 formdata example 错误。pr#512
- 修复 url 中使用环境变量表达式时解析错误，#515
发展情况
smart-doc 开源维护接近五年，目前很多功能已经非常稳定，国内有很多的用户。码云 star 3k+，github star 1k+ 。smart-doc 官方布道的企业级文档管理系统 torna 的 docker 镜像下载量超过 10k 。国内已有数家知名司在使用 smart-doc ，如：科大讯飞、小米、一加、顺丰、马蜂窝、同程旅行等。smart-doc+torna 的整套 API 管理体系已经被很多公司落地使用。
 |
1
zgcwkj 2023-06-12 10:58:39 +08:00
和 Swagger 比，有什么优势？
|
 |
3
pigf 2023-06-12 13:35:11 +08:00
好用，在用，支持
|
 |
4
yifeng33 2023-06-12 13:35:27 +08:00
我们组好像准备用这个，让我完善 java doc
|
 |
5
Masoud2023 2023-06-12 13:43:20 +08:00
真要怕侵入应该连这个也不要用直接手写 openapi ，都写 java 这么啰嗦的东西了，写几行 swagger 注解我觉得也没什么。
|
 |
6
smartdoc647 OP  1
@Masoud2023 真没几个人愿意手写文档，或者 openapi 这种结构化文档的，没必要把时候花费在这种对技术毫无增长的东西上，工具的目的是提升效率替代简单的工作。swagger 在中小公司还好，大厂基本用不起来，不要问我怎么知道的，毕竟我因为开源和阿里、蚂蚁、字节、华为都有接触。还有是不要有什么语言偏向性，大佬都是多语言并行的，像我这种菜狗也是 java 和 golang 主力开发并行，两个语言也都有开源贡献。我身边搞 java 的同事拿着 apache commiter 简直香的不行，走到哪里圈子里都会尊敬。
|
 |
7
LeegoYih 2023-06-12 14:13:17 +08:00
👍🏻提供另一种解决方案
|
 |
8
iminto 2023-06-12 14:27:16 +08:00
我直接 javadoc ，这才是真的零侵入，不需要导包。
javadoc 不支持的注解，还能用 tag 进行扩展。 |
 |
9
zhangwugui 2023-06-12 15:45:01 +08:00
支持，项目中已经使用，已本地化部署
|
 |
10
jamel 2023-06-12 15:58:44 +08:00
支持 grpc-spring-boot-starter 不
|
 |
11
alteremliu 2023-06-12 16:01:16 +08:00
已经在使用了，好评
|
|
12
smartdoc647 OP @iminto 可以分享下解决方案，如果 javadoc 完整解决 rest 业务接口的文档其实挺好的，但是我的了解是类嵌套这种肯定 javadoc 不行，工具的目的还是在于让程序员把事情做好的同时，少写点东西，所以 smart-doc 就是能自动解析的都给自动解析，
|
 |
13
tudou527 2023-06-12 18:29:48 +08:00
我来提供一个基于 javadoc 的方案： https://oneapi.app （支付宝内部方案的开源版本）
|
 |
14
totoro52 2023-06-12 18:31:59 +08:00
看看，不喜欢 sw 的牛皮癣一样存在的注解
|
|
15
smartdoc647 OP @tudou527 你们这个思路也可以，非常棒，主要是可以不改项目。这也是我之前想改造的方式。你们其实可以做些宣传，把 case 补起来。小公司的代码 case 是比较多的，大厂规范度相对高点。不过这类工具未来其实是可以用大模型训练去取代的，生成 api 这个完全可以训练出来。
|
|
16
iminto 2023-06-13 08:31:35 +08:00
@smartdoc647
javadoc 原生支持 param,link 这些注解，但是对于 restful 的接口，还需要譬如 method ，path 这些参数，javadoc 支持 tag/taglet 这些扩展语法，能让生产的文档可读性更加。 我啥都没弄，就是扩展了下 javadoc 的注解，让它生成的文档更像那么回事 |
 |
17
WashFreshFresh 2023-06-13 09:26:47 +08:00
挺好的，可惜我司项目不支持，统一入口，通过参数反射调用不同 service 的不同 method 当 controller...
|
 |
18
misaka19000 2023-06-14 23:05:20 +08:00
最近在用 qdox 解析源码，用的就是作者大大发布的 maven 版本，居然在这里看到了原作者了~~~蹭蹭😁
|
|
19
smartdoc647 OP @jamel grpc 不支持，但是欢迎参与共建
|
Select Language