夜雨聆风
Kaleido-AI文档(二):写代码还是写注解?受够了 Swagger,我换成了 Smart-Doc
以前以为 Swagger 是救星，结果用久了发现是“巨坑”： 满屏全是 swagger的注解，业务代码被淹没，注解写得比代码还多！
最近在做 Kaleido-AI 项目，我果断弃用了Swagger，全面拥抱 Smart-Doc 。
有图有真相，我最早就是用的swagger：
为什么要抛弃 Swagger？
Swagger 虽然生态强大，但有几个无法忽视的痛点：
-
强侵入性： 这是最大的槽点。为了生成文档，你必须在 Controller 和 DTO 上加一大堆注解。这导致代码可读性急剧下降，业务逻辑被“污染”。
-
维护成本高：代码改了，注解常常忘了改。最后导致文档和代码不一致，文档失去了参考价值。
-
生产环境风险：如果配置不当，Swagger UI 可能会在生产环境暴露接口定义，存在安全隐患。
为什么选择 Smart-Doc？
Smart-Doc 是一款基于 Java 源代码分析的 API 文档生成工具，它的核心理念是 “零注解、零侵入”。
-
基于 Javadoc 分析： 它直接读取你的 Java 源代码和注释（Javadoc）。只要你代码写得规范，注释写得清楚，文档就自动生成了！
/*** 获取用户信息* @param id 用户ID* @return 用户详情*/@GetMapping("/{id}")public Result<User> getUser(@PathVariableLong id) { ... }
-
支持多种格式： Smart-Doc 可以生成 HTML5、Markdown、Postman Collection、OpenAPI 3.0+ 等多种格式。生成的 HTML 页面不仅美观，还支持在线调试（Debug）。
-
支持 Dubbo RPC： Kaleido 项目中使用了 Dubbo，Smart-Doc 也能完美支持 RPC 接口文档的生成，这是很多其他工具做不到的。
-
构建时生成： 它通过 Maven 插件在编译时生成文档，不随应用启动，不占用运行时资源，生产环境绝对安全。
🛠️ 实战：Kaleido 项目如何生成接口文档？
在我们的 Kaleido Server 项目中，我已经配置好了 Smart-Doc。下面是详细的操作指南。
1. 核心配置 (smart-doc-config.json)
我们在每个微服务模块（如 kaleido-admin, kaleido-auth 等）的 src/main/resources 目录下都放置了一个 smart-doc-config.json 配置文件。
以 Kaleido Admin (管理后台) 为例：
{"serverUrl": "http://localhost:9010/kaleido-admin/", // 服务器地址"allInOne": true, // 是否将所有文档合并为一个文件"outPath": "../doc/api/admin", // 输出路径（自动生成到项目根目录的 doc/api/admin 下）"coverOld": true, // 覆盖旧文档"packageFilters": "com.xiaoo.kaleido.admin.trigger.controller.*", // 扫描的包路径"projectName": "Kaleido 管理后台服务 API 文档","style": "xt256", // 文档风格"createDebugPage": true, // 生成支持在线调试的页面"requestHeaders": [ // 设置全局请求头，如 Token{"name": "Authorization","type": "string","desc": "认证令牌，格式：Bearer {token}","required": false}]}
2. Maven 插件配置
在项目的根目录 pom.xml 中，我们集成了 smart-doc-maven-plugin：
<plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>${smart-doc.version}</version><configuration><!-- 指定配置文件路径 --><configFile>src/main/resources/smart-doc-config.json</configFile><projectName>${project.name} API 文档</projectName></configuration><executions><execution><!-- 绑定到 compile 阶段，编译即生成 --><phase>compile</phase><goals><goal>html</goal></goals></execution></executions></plugin>
3. 如何生成文档？
在 IDEA 中，你有两种方式生成文档：
方式一：命令行（推荐）
在项目根目录下打开终端，执行以下命令：
# 编译并生成文档（因为插件绑定了 compile 阶段）mvn clean compile -DskipTests# 或者单独运行 smart-doc 插件目标mvn smart-doc:html -DskipTests
方式二：IDEA Maven 面板
-
打开右侧 Maven 面板。 -
找到具体的子模块（例如 kaleido-admin）。 -
展开 Plugins->smart-doc。 -
双击 smart-doc:html。
4. 查看文档
执行成功后，文档会自动输出到项目根目录的 doc/api/ 文件夹下。
-
管理后台文档： doc/api/admin/index.html -
认证服务文档： doc/api/auth/index.html -
RPC 接口文档： doc/rpc/index.html(位于kaleido-api模块配置中)
直接用浏览器打开 index.html，你就能看到清爽、专业的接口文档，并且可以直接在页面上输入 Token 进行接口调试，其中postman.json可以直接导入Postman或Apifox进行接口调试。
总结
Smart-Doc 让文档回归代码本身，强制开发者写好 Javadoc，这本身就是一种良好的编码规范。如果你也受够了 Swagger 的注解地狱，不妨在你的下一个项目中试试 Smart-Doc！
