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

💡 前言

随着微服务架构的普及，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 插件配置：

xml 复制代码

    <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：

java 复制代码

/**
 * 用户控制器
 * @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 对象：

java 复制代码

/**
 * 用户实体类
 *
 * @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`)

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 文档自动化生成与管理。

🎯 点赞、收藏、转发本文，让更多开发者受益！