当前位置：首页 > backend >正文

Spring Boot 整合 Smart-Doc：零注解生成 API 文档，告别 Swagger

backend 2025/6/19 9:57:28

💡 前言

随着微服务架构的普及，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` 是否包含对应包路径
字段缺失	检查是否有注释或字段是否被忽略
输出格式不满足需求	修改配置文件或自定义模板