V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 1431 天前的主题，其中的信息可能已经有所发展或是发生改变。

在过去，尤其是 java web 服务端开发者，绝大多数都采用 swagger 来生成项目的接口文档。虽然 swagger 很多的注解让很多代码洁癖开发者很是无奈，但是由于缺乏其他突破性的解决方案的开源，很多人只能忍痛使用。

2018 年 smart-doc 的开源终于打破的 swagger 注解侵入性的魔咒。smart-doc 完全采用源代码扫描分析来生成文档，工具通过解析代码中的接口定义、解析注释、分析项目依赖加载源码帮助用户生成接口文档。下面来看看 smart-doc 的功能特性。

简介

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，smart-doc 在业内率先提出基于 JAVA 泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照 java-doc 标准编写注释，smart-doc 就能帮你生成一个简易明了的 Markdown 、HTML5 、Postman Collection2.0+、OpenAPI 3.0+的文档。

smart-doc vs swagger

功能特性	smart-doc	swagger
代码侵入	无	注解侵入性严重
集成复杂度	简单，只需插件	偏复杂、硬编码配置
插件支持	有 gradle 和 maven 插件	无插件
openapi 规范支持	支持 openapi 3.0	完全支持 openapi 的版本
CI 构建集成	可在 ci 构建阶段使用 maven 或者 gradle 命令启动插件生成文档	不支持
维护持续性	值得信赖，开源后用户基础多，开源两年多一直持续维护	全球用户多，开源维护值得信赖
接口 debug	2.0.0 版本开始已经支持 debug，debug 页面简洁大方，支持文件上传下载测试	支持，界面丑、对接口兼容度不如 smart-doc 、不支持文档下载测试。

smart-doc 目前已经实现了 swagger 所支持的功能，并且针对国内用户需求附加了很多契合实际的使用的功能。使用文档也非常完善，你不需要到处百度如何集成，你只需要看项目仓库中的 wiki 文档即可学习使用。

项目地址

https://gitee.com/smart-doc-team/smart-doc

debug 页面

致谢

smart-doc 从 2018 年开源发展到今天，离不开国内很多用户和很多企业的支持。从当初一个仅仅支持 restful 接口文档生成的工具，逐渐发展到支持 dubbo 、支持开发接口测试。都是靠着国内用户一个一个需求推动完善的。在这里对 smart-doc 的用户说声感谢！

smart-doc

swagger

文档

生成

23 条回复 • 2020-12-22 20:15:43 +08:00

pxlxh

2020-12-22 10:07:08 +08:00

嗯和我想的 swagger 不一样

iceecream

2020-12-22 10:09:02 +08:00

嗯，是我想的 swagger ！！

hantsy

2020-12-22 10:17:29 +08:00

要搞清楚一个基本东西，Swagger 产品链背后是 OpenAPI 3 。0 标准。

API 开发两个经典模式：

1 。代码优先，从代码注释生成 API Schema （比如经验的 SpringFox 项目，Microprofile 中 OpenAPI 标准都支持），由 SwaggerUI 显现出来。
2 。设计优先，Swagger 提供在线 Editor，先写好 Schema （ Yaml 或者其他格式），再生成 Dummy Codes （或者完全手写），事先编辑好的 Schema 文件可以由 Swagger UI 直接可视化。（大型项目，有经验丰富的架构师做阵比较适用）

嗯，似乎这个 SmartDoc 不关心第二方式。

那么第一种方式，有多少局限性，目前没用过，无从得知。

tinycold

2020-12-22 10:19:52 +08:00 via Android

"酸菜鱼不要这么做了，两种方式让你做出更鲜美的酸菜鱼"

walker748

2020-12-22 10:21:20 +08:00

咦，不是我想的 swagger ！！

hantsy

2020-12-22 10:24:26 +08:00

>>>CI 构建集成

这个我给你看一个我几年前写的。

https://github.com/hantsy/building-restful-apis-with-springmvc-gitbook/blob/master/swagger.md

Swagger/OpenAPI 生态决定的它在使用上的灵活性。

smartdoc647

2020-12-22 10:40:56 +08:00

@hantsy 首先非常欣赏你丰富的研发经验。第二种方式本身和这个工具不存在冲突，当然实际落地也很难。
smart-doc 开源的初衷也不是奔着造轮子去的，在使用 smart-doc 之前我也使用过你提到的这些工具，可能是我经验欠缺吧没有用好它们，反正就是对这些工具够不满意，然后重新开发了这个工具。后来在不断的开源迭代中，发现得到国内很多开发者的支持，在这个发展过程中，我们也一直关注国内外相关的工具、也非常重视像 OpenAPI 3.0 这样的行业标准。因此我们也做大量的支持和测试。

hantsy

2020-12-22 11:26:14 +08:00

@smartdoc647 开篇说的支持 Java Rest API, 这个有运行环境和框架限制吗？

比如支持 Jaxrs （ Jakarta Restful Web Service ）标准吗？

* https://github.com/hantsy/ee7-jaxrs-sample/wiki/4-swagger 这个之前用的。Java EE 8 有了 Microprofile OpenAPI 标准，内置支持 Jaxrs 。

支持在其他框架运行吗？比 Quarkus，Helidon，Micronaunt，Vertx 等。

* https://github.com/hantsy/quarkus-sample/blob/master/post-service/ 包含 OpenAPI （使用的是 Microprofile OpenAPI 标准集成）

支持 Spring 5.0 加入的中支持 Reactive Streams 标准吗？还有 KotlinDSL ？支持 Functional 方式的 Router 吗？

Spring 5 以来的变化，可以给开发人员带来不同的使用组合，我归结为几种编程模式。

* https://github.com/hantsy/spring-puzzles/tree/master/programming-models 目前 Spring Fox 也只能支持传统 WebMvc，和使用 ReactiveStreams 的 Controller 形式（试验性支持），其他几种的无能为力。

hantsy

2020-12-22 11:29:26 +08:00

比如这个 https://github.com/hantsy/spring-puzzles/blob/master/programming-models/webmvc-fn/src/main/java/com/example/demo/DemoApplication.java#L67

chendy

2020-12-22 11:31:44 +08:00

做过类似的东西，折腾了快两年，最后放弃
得出的结论是：应该是先设计再实现，接口文档应该是独立于代码实现而不是在代码实现里的

hantsy

2020-12-22 11:35:25 +08:00

@chendy 不管是重复发明轮子，还是新创造，做开源需要的坚持下去。

cco

2020-12-22 11:44:13 +08:00

标题有些蛋疼。不是为了看内容来评论的，就单纯吐槽这种标题党！！！

zgray

2020-12-22 11:56:45 +08:00

@hantsy 我比较赞同你的观点，我更想要设计优先的 API 编辑器。因为团队规模稍微大点的时候，我根本不知道我的团队成员会写出什么乱七八糟的接口，我唯一能寄希望的是，先把接口设计先做好，他们去实现逻辑。

顺便想问下有没有推荐的工具，swagger editor 还是有点难用。

smartdoc647

2020-12-22 12:40:40 +08:00

@chendy 重新搞东西都是很难的，需要耗费很多精力，smart-doc 开发的过程中也经历过很艰难的时候想放弃，但是后来因为得到很多开发者的喜爱和一些大公司的引入才有了维护下去的动力。关于是以代码先行还是设计先行，这和 smart-doc 这种工具本身不冲突，我们团队很多项目也是设计先行，但是根据设计写好代码后可以通过工具扫描代码生成接口文档，比如 openapi 的文档数据，然后可以把这种文档直接发送到集中化的文档管理系统中，这对于大型微服务文档集中化管理还是提供了很多遍历的。