Smart-doc 深度评测：不写一行注解，Java API 文档自动生成

说实话，我第一次看到 Smart-doc 的时候，心里是有点怀疑的。一个 Java API 文档生成工具，居然号称”零注解侵入”？要知道在这个领域，Swagger 几乎就是行业标准，而 Swagger 的核心就是那一堆 @ApiOperation、@ApiParam 之类的注解。没有注解，它怎么知道你的接口是干什么的？

带着这个疑问，我花了一个下午仔细研究了这个项目。现在我可以负责任地说：Smart-doc 确实有点东西。

项目背景：为什么要有 Smart-doc？

Smart-doc 来自同程旅行开源团队，GitHub 上目前 1,592 个 star，不算特别火，但社区活跃度还不错。项目的核心理念很简单——基于源码分析自动生成文档，不需要在代码里加任何额外注解。

这个理念的诞生其实很好理解。用 Swagger 的朋友应该都经历过这种痛苦：

• 每写一个接口就要加一堆注解，代码变得臃肿
• 注解和实际代码不同步，文档成了”谎言”
• 团队新人要学一套 Swagger 注解规范
• 有些项目（比如老项目）根本不想引入 Swagger 依赖

Smart-doc 的创始人显然被这些问题折磨过，所以干脆换了一条路：既然 Java 代码本身就有 Javadoc 注释，接口定义本身就包含了参数类型、返回值、URL 路径这些信息，为什么还要额外加注解呢？直接从源码里解析不就行了？

这个想法听起来简单，实现起来却不容易。Java 的泛型擦除、复杂嵌套对象、继承关系、第三方依赖……这些都要处理。Smart-doc 能做到这一点，说明背后的源码分析引擎确实下了功夫。

（对了，原仓库 TongchengOpenSource/smart-doc 已经在 2025 年 12 月被归档了，现在活跃维护的是 smart-doc-group/smart-doc，最新版本是 3.1.2。）

核心功能详解

1. 真正的零注解侵入

这是 Smart-doc 最大的卖点，也是我最想验证的功能。

实际测试下来，确实如此。你只需要写正常的 Javadoc 注释：

/**
 * 获取用户信息
 * @param userId 用户ID
 * @return 用户详情
 */
@GetMapping("/user/{userId}")
public User getUser(@PathVariable Long userId) {
    return userService.getById(userId);
}

不需要 @ApiOperation，不需要 @ApiParam，Smart-doc 直接从方法签名和 Javadoc 里提取所有信息。生成出来的文档包含接口名称、参数说明、返回值结构，甚至连字段注释都能从实体类的 Javadoc 里读出来。

说实话，这个功能让我有点惊喜。因为我之前试过几个号称”零侵入”的工具，最后发现要么功能残缺，要么还是要写一些配置文件。Smart-doc 在这方面确实做到了”开箱即用”。

2. 自动推导返回结构

Smart-doc 的返回结构推导能力比我预期的要强。比如你的接口返回 Result<User>，它不仅能识别出外层是 Result 包装类，还能递归解析 User 对象里的每个字段，包括字段类型、是否必填、字段注释。

更厉害的是它支持异步接口——Callable、Future、CompletableFuture 这些都能正确解析。对于用了大量异步编程的项目来说，这个功能挺实用的。

3. 多格式输出支持

Smart-doc 支持的输出格式相当丰富：

• HTML5：生成漂亮的静态文档页面，自带搜索功能
• Markdown：适合放在 GitHub 或文档站点
• Word：给产品经理或客户看（虽然我觉得程序员都不太喜欢 Word）
• OpenAPI 3.0：可以对接 Swagger UI
• Postman Collection：直接导入 Postman 做接口测试
• JMeter 脚本：做压测的时候省不少事

我个人最常用的是 HTML 和 Postman 导出。HTML 文档可以直接部署到内网服务器，Postman 文件发给前端同事，两边都方便。

4. 内置 Debug 页面

从 2.0.1 版本开始，Smart-doc 可以生成一个 debug.html 页面，功能类似 Swagger UI，可以直接在页面上测试接口。这个页面是用原生 JS 写的，没有依赖任何前端框架，加载速度很快。

不过要吐槽一下，这个 debug 页面需要配置跨域才能正常使用。如果你在 IDEA 里直接打开 HTML 文件，请求会报跨域错误。得在 Spring Boot 里加一段 CORS 配置，或者把文档部署到服务器上访问。这个细节文档里提到了，但第一次用的时候我还是踩了坑。

5. Torna 集成（企业级文档管理）

如果你是在企业环境里用，Smart-doc + Torna 的组合挺值得考虑。Torna 是一个开源的 API 文档管理平台，Smart-doc 可以把生成的文档自动推送到 Torna 上，实现文档的版本管理和团队协作。

配置也很简单，在 smart-doc.json 里加几行：

{
  "appToken": "your-token",
  "openUrl": "http://torna-server/api",
  "replace": true,
  "debugEnvName": "测试环境",
  "debugEnvUrl": "http://127.0.0.1:8080"
}

然后执行 mvn smart-doc:torna-rest 就能自动推送。对于需要维护大量接口文档的团队来说，这个工作流确实能省不少事。

实际使用场景

场景一：老项目补文档

这是我个人觉得 Smart-doc 最适合的场景。很多老项目一开始没写文档，后来想补的时候发现工程量巨大。用 Smart-doc，只要代码里原本就有 Javadoc（哪怕写得不太规范），基本都能自动生成一份能看的文档。虽然不能 100% 替代人工写的文档，但至少是个很好的起点。

场景二：不想引入 Swagger 依赖的项目

有些项目对依赖特别敏感，比如 SDK 项目、基础框架项目，引入 Swagger 会增加不必要的依赖链。Smart-doc 是编译期工具，只在构建时使用，不会打入生产包，这个优势很明显。

场景三：多模块项目的统一文档

Smart-doc 支持从外部依赖加载源码生成字段注释，包括 sources jar 包。对于多模块项目或者依赖了内部公共包的项目，这个功能很实用。你可以在一个模块里生成整个系统的接口文档。

快速上手

Smart-doc 的使用方式有两种：Maven 插件和 Gradle 插件。这里以 Maven 为例：

第一步，在 pom.xml 里添加插件：

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <configFile>./src/main/resources/smart-doc.json</configFile>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

第二步，在 resources 目录下创建 smart-doc.json：

{
    "outPath": "./src/main/resources/static/doc",
    "serverUrl": "http://127.0.0.1:8080",
    "createDebugPage": true
}

第三步，执行命令生成文档：

mvn -Dfile.encoding=UTF-8 smart-doc:html

生成的文档会在 static/doc/ 目录下，启动 Spring Boot 后访问 http://localhost:8080/doc/index.html 就能看到了。

如果你想生成其他格式，把命令里的 html 换成 markdown、openapi、postman、torna-rest 就行。

优缺点分析

优点

• 零注解侵入：这个是真的，不是营销话术。代码里不需要任何 Smart-doc 相关的注解。
• 学习成本低：如果你本来就会写 Javadoc，那基本不用学新东西。
• 多格式输出：HTML、Markdown、Postman、OpenAPI、JMeter、Word，覆盖面很广。
• 编译期生成：不增加运行时依赖，不影响应用性能。
• 源码分析能力强：泛型、嵌套对象、异步接口都能正确处理。

缺点（必须吐槽）

• 文档质量依赖 Javadoc：如果你的代码注释写得稀烂，生成的文档也会稀烂。Smart-doc 不会凭空创造描述信息，它只能解析你已有的内容。有些团队代码注释本来就少，用 Smart-doc 生成的文档会显得很单薄。
• 功能不如 Swagger 丰富：Swagger 的注解可以控制很多细节，比如参数示例值、隐藏字段、自定义响应码等。Smart-doc 虽然也有配置项，但灵活度确实不如注解驱动的方式。
• debug 页面体验一般：相比 Swagger UI，Smart-doc 的 debug 页面功能比较基础，UI 也不够精致。如果只是简单测试接口够用，但复杂场景（比如文件上传、认证头管理）体验不如 Swagger。
• 社区规模偏小：1,592 个 star 和 Swagger 的 20k+ 没法比。遇到问题时，Stack Overflow 上的答案不多，主要靠 GitHub Issues 和官方文档。
• 原仓库已归档：TongchengOpenSource/smart-doc 已经归档，虽然代码还在，但给人一种项目”被放弃”的感觉。虽然 smart-doc-group 还在继续维护，但这个切换过程可能会让一些用户困惑。

与竞品对比

特性	Smart-doc	Swagger (SpringDoc)
注解侵入	零侵入	需要大量注解
学习成本	低（会 Javadoc 即可）	中（需学 Swagger 注解）
输出格式	HTML/Markdown/Postman/OpenAPI/Word/JMeter	HTML/OpenAPI/Postman
运行时依赖	无	有（swagger-ui 等）
灵活性	中（靠配置文件）	高（注解可精细控制）
社区规模	小（1.5k stars）	大（20k+ stars）
调试页面	基础功能	功能完善

怎么选？

• 如果你讨厌写注解、项目对依赖敏感、或者想给老项目补文档，Smart-doc 是更好的选择。
• 如果你需要精细控制文档表现、团队已经熟悉 Swagger、或者需要完善的在线调试功能，SpringDoc 更合适。

其实这两个工具不是完全互斥的。Smart-doc 可以生成 OpenAPI 规范，然后你用 Swagger UI 来展示，算是各取所长。

适合人群与总结

Smart-doc 最适合这几类人：

1. 讨厌代码里一堆注解的开发者——如果你看到 @ApiOperation 就烦，Smart-doc 会让你舒服很多。
2. 维护老项目的工程师——代码里已经有 Javadoc，但缺一份像样的接口文档。
3. 对依赖敏感的团队——比如 SDK 开发、基础框架团队，不想把 Swagger 打进生产包。
4. 想快速产出文档的中小团队——不需要太复杂的文档定制，能用就行。

总结一下，Smart-doc 是一个”够用且省心”的工具。它不会给你最强大、最灵活的文档生成能力，但它确实做到了”零侵入”和”低学习成本”。在这个细分领域，能做到这两点就已经很有价值了。

如果你现在用的是 Swagger，不一定非要换成 Smart-doc。但如果你在启动新项目，或者正被 Swagger 的注解折磨，那 Smart-doc 绝对值得一试。

至少，它让我重新相信了一件事：好的工具应该是帮你省事的，而不是给你增加负担的。