Spring Boot 整合 Smart-Doc的详细过程(零注解生成 API 文档,告别 Swagger)

目录

• 前言
• 一、什么是 Smart-Doc？
• 二、Spring Boot 整合 Smart-Doc 步骤详解
• Step 1：添加 Maven 插件
• Step 2：编写符合规范的 Java 注释
• 三编程客栈、常见问题排查指南
• 四、结语

前言

随着微服务架构的普及，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 返回用户对象
    js */
    @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
 *
 php**/
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：效果展示

三、常见问题排查指南

四、结语

Smart-Doc 凭借其“零注解 + 强大解析能力”的特性，成为替代传统 Swagger 的理想选择。相比 Swagger，它更加简洁、高效，特别适合那些追求代码整洁、希望减少注解污染的项目。

无论是企业内部系统、SaaS 平台，还是微服务架构，都可以借助 Smart-Doc 实现高质量的 API 文档自动化生成与管理。

到此这篇关于Spring Boot 整合 Smart-Doc：零注解生成 API 文档，告别 Swagger的文章就介绍到这了,更多相关Spring Boot Smart-Doc API 文档内容请搜索编程客栈(www.devze.com)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程客栈(www.devze.com)！