律师网站 扁平化网站整站优化推广方案
💡 前言
随着微服务架构的普及，API 接口文档的重要性日益凸显。传统的 Swagger（如 SpringFox、SpringDoc）虽然功能强大，但需要大量的注解来描述接口信息，增加了代码冗余和维护成本。今天介绍的开源工具——Smart-Doc，它基于 Java 注释和 Javadoc 规范自动生成统一、规范的 API 文档，无需任何额外注解，真正做到了“写好注释 = 写好文档”。
本文将详细介绍如何在 Spring Boot 项目中整合 Smart-Doc，以及使用 Maven 插件一键生成多种格式的 API 文档。
📦 一、什么是 Smart-Doc？
Smart-Doc 是一款通过解析 Java 源码注释来自动生成 API 文档的开源工具，具有以下特点：
- 零注解：不依赖任何第三方注解，仅需写好 Java 注释即可。
- 多格式支持：支持 HTML、Markdown、OpenAPI、Postman JSON 等。
- 支持 Spring Boot：完美兼容 Spring MVC、Spring WebFlux。
- 构建时生成：对运行时性能无影响。
🔧 二、Spring Boot 整合 Smart-Doc 步骤详解
Step 1：添加 Maven 插件
首先，在你的 pom.xml 文件中添加 Smart-Doc 的 Maven 插件配置：
<build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin><!--api文档 begin--><plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>2.3.5</version><configuration><!--指定生成文档的使用的配置文件--><configFile>${basedir}/src/main/resources/smart-doc.json</configFile></configuration><executions><execution><!--如果不需要在执行编译时启动smart-doc，则将phase注释掉--><phase>compile</phase><goals><goal>html</goal></goals></execution></executions></plugin><!--api文档 end--></plugins></build>
Step 2：编写符合规范的 Java 注释
Smart-Doc 依赖于标准的 Java 注释生成文档。确保为你的 Controller 和 DTO 类编写详细的注释。
示例 Controller：
/*** 用户控制器* @Author: pzj* @Date: 2025/6/12 18:59**/
@RestController
@RequestMapping("/users")
public class UserController {/*** 获取用户详情* @param id 用户ID* @return 返回用户对象*/@GetMapping("/{id}")public User getUserById(@PathVariable Long id) {return new User(id, "张三");}/*** 创建新用户* @param user 用户实体* @return 创建结果*/@PostMapping("/add")public String createUser(@RequestBody User user) {System.out.println(user);return "创建成功";}
}
示例 DTO 对象：
/*** 用户实体类** @Author: pzj* @Date: 2025/6/12 19:00***/
public class User implements Serializable {/*** 主键*/private Long id;/*** 用户名*/private String userName;public User(Long id, String userName) {this.id = id;this.userName = userName;}public Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getUserName() {return userName;}public void setUserName(String userName) {this.userName = userName;}
}Step 3：添加配置文件 (src/main/resources/smart-doc-config.json)
{//指定后端服务访问地址,"serverUrl": "http://127.0.0.1:8090",//指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看,"outPath": "src/main/resources/static/doc/api",//是否开启严格模式,"isStrict": false,//是否将文档合并到一个文件中,"allInOne": true,//是否创建可以测试的html页面,"createDebugPage": true,//controller包过滤（换成你的路径）,"packageFilters": "com.example.smartdoc.controller",//基于highlight.js的代码高设置,"style": "xt256",//配置自己的项目名称,"projectName": "smart-doc文档",//是否显示接口作者名称,"showAuthor": false,//自定义设置输出文档名称,"allInOneDocFileName": "index.html",//文档变更记录，非必须,"revisionLogs": [{//文档版本号,"version": "1.0",//文档修订时间,"revisionTime": "2020-12-31 10:30",//变更操作状态，一般为：创建、更新等,"status": "update",//文档变更作者,"author": "peng_zj",//变更描述,"remarks": "修改了XXXX功能"}]
}
Step 4：运行插件生成文档
在maven插件中选择想要的类型生成对应的文档：
生成的文档默认位于 target/smart-doc/html/index.html。打开浏览器访问该文件，即可看到结构清晰、内容丰富的 API 文档页面。
Step 5：效果展示
🧩 四、常见问题排查指南
| 问题 | 解决方案 |
|---|---|
| 文档未生成 | 检查 Maven 插件是否正确配置，执行命令是否正确 |
| 接口未扫描到 | 检查 packageFilters 是否包含对应包路径 |
| 字段缺失 | 检查是否有注释或字段是否被忽略 |
| 输出格式不满足需求 | 修改配置文件或自定义模板 |
📘 五、结语
Smart-Doc 凭借其“零注解 + 强大解析能力”的特性，成为替代传统 Swagger 的理想选择。相比 Swagger，它更加简洁、高效，特别适合那些追求代码整洁、希望减少注解污染的项目。
无论是企业内部系统、SaaS 平台，还是微服务架构，都可以借助 Smart-Doc 实现高质量的 API 文档自动化生成与管理。
🎯 点赞、收藏、转发本文，让更多开发者受益！