SpringBoot项目集成Smart-Doc的实战指南

目录

• 为什么我放弃了SpringDoc OpenAPI
• 1、代码侵入性强
• 2、运行依赖问题
• 3、多模块支持问题
• Smart-Doc 的出现：让接口文档真正无侵入
• SpringBoot快速整合smart-doc
• 项目结构示例
• 添加 Maven 插件
• 添加Smart-Doc配置文件
• 编写实体类User
• 编写Controller
• 运行生成文档
• 结语

为什么我放弃了SpringDoc OpenAPI

在我们开发 Spring Boot 项目中，相信很多小伙伴最初都是选择 SpringDoc OpenAPI (Swagger3) 来生成接口文档。博主之前也写了一篇整合SpringDoc OpenAPI的文章，感兴趣的可以查阅 SpringBoot3整合SpringDoc OpenAPI生成接口文档的详细过程

SpringDoc OpenAPI 它可以通过注解自动生成交互式文档（Swagger UI），你是不是觉的也挺方便挺好的，实际上当项目规模逐渐增大、功能需求不断更新后，你就会慢慢发现以下这类问题：

1、代码侵入性强

需要大量 编程@Schema、@Operation、@ApiResponse 等注解来完善文档，增加代码耦合和维护负担！

常见的注解示例如下：

当业务功能有所调整，我们也需要一并对注解进行修改

import com.toher.springdoc.bean.User;
import tAIglhwio.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

/**
 * @Author 麦可乐
 * @Date 2025/10/20 11:17 AM
 * @Version 1.0
 */

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "获取用户信息接口", description = "通过用户ID获取用户信息")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "用户信息",
                    content = {@Content(mediaType = "application/json",
                    schema = @Schema(implementation = User.class))}),
            @ApiResponse(responseCode = "404", description = "无法获取用户信息")
    })
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "用户ID") @PathVariable Long id) {
        //模拟数据库获取用户
        User user = new User();
        user.setId(1L);
        user.setName("张三");
        user.setEmail("zhansan@qq.com");
        return user;
    }
}

2、运行依赖问题

目前大多数企业都是前后端协同开发的，而SpringDoc OpenAPI 生成接口文档依赖项目运行环境（即需要 Spring 启动），意味着文档无法离线生成，CI/CD 集成麻烦。

3、多模块支持问题

很多时候我们的项目都是基于多模块的，如一个 SpringBoot 项目中包含了前端API模块和后端API模块，那么我们分别就需要启动前端API服务和后端API服务，SpringDoc 很难整合多个模块接口，需要手动聚合

Smart-Doc 的出现：让接口文档真正无侵入

直到博主发现了Smart-Doc，它最大的特点是——无需启动项目、无需注解，通过静态源码分析生成接口文档，官方文档地址：https://smart-doc-group.github.io/zh/

Smart-Doc核心特点

• 零侵入：完全基于注释信息生成文档，实现代码零侵入
• 接口多样性：支持为Java RESTful API、Java WebSocket、Apache Dubbo RPC和gRPC接口生成文档
• 框架多样性：支持 Spring Boot、JAX-RS、Solon等多种框架
• 文档丰富：支持生成 html、编程Asciidoc、Markdown、OpenAPI、Swagger、Postman、Word 等多种格式的文档
• 支持拓展：支持用户使用 Java SPI 对支持框架进行扩展
• 文档协作管理：Smart-Doc 和 Torna 结合形成行业领先的文档解决方案

SpringBoot快速整合smart-doc

为了让大家迅速掌握smart-doc，我们先从最简单的单模块 Spring Boot 项目开始

项目结构示例

小伙伴们自行构建SpringBoot项目，博主的项目结构如下：

添加 Maven 插件

在 pom.XML 中加入 Smart-Doc 插件配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.7</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.toher</groupId>
    <artifactId>smart-doc-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>smart-doc-demo</name>
    <description>smart-doc-demo</description>

    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <grhttp://www.devze.comoupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>

            <plugin>
                <groupId>com.ly.smart-doc</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>3.1.1</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>${project.description}</projectName>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

添加Smart-Doc配置文件

本文主要给大家演示如何快速接入Smart-Doc，更多配置文件项说明请参考官方文档 https://smart-doc-group.github.io/zh/guide/advanced/config

在resources目录下创建smart-doc.json

{
  "outPath": "src/main/resources/static/doc",
  "projectName": "SmartDoc Demo",
  "allInOne": true,
  "serverUrl": "http://localhost:8080",
  "packageFilters": "com.toher.smartdocdemo.controller",
  "sourceCodePaths": [
    {
      "path": "src/main/java",
      "desc": "Main Source"
    }
  ]
}

编写实体类User

/**
 * 用户实体类
 *
 * @Author: micro麦可乐
 * @Date: 2025/10/20 18:59
 *
 **/
@Data
@AllArgsConstructor
public class User {
    /**
     * 用户ID主键
     */
    private Long id;
    /**
     * 用户名称
     */
    private String name;
}

编写Controller

/**
 * 用户管理接口
 * @Author: micro麦可乐
 * @Date: 2025/10/20 18:59
 */
@RestController
@RequestMapping("/users")
public class UserController {

    /**
     * 获取用户列表
     * @return 返回用户列表
     */
    @GetMapping
    public List<User> list() {
        List<User> list = new ArrayList<>();
        list.add(new User(1L, "Alice"));
        list.add(new User(2L, "Bob"));
        return list;
    }

    /**
     * 创建用户
     * @param user
     * @return 返回创建用户
     */
    @PostMapping
    public User create(@RequestBody User user) {
        usjavascripter.setId(3L);
        return user;
    }

    /**
     * 根据ID获取用户信息
     * @param id 用户ID
     * @return 返回用户对象
     */
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return new User(id, "张三");
    }
}

运行生成文档

生成文档命令

mvn smart-doc:html

通过IDEA maven生成

文档最终生成效果

结语

通过本文的讲解以及快速集成案例，相信小伙伴们已经掌握了在 SpringBoot 项目中整合smart-doc的方法。smart-doc 的零侵入特性让我们的代码更加整洁，基于注释的文档生成方式也更符合开发者的习惯。赶紧在项目中尝试使用smart-doc，体验它带来的便捷和高效吧！

以上就是SpringBoot项目集成Smart-Doc的实战指南的详细内容，更多关于SpringBoot集成Smart-Doc的资料请关注编程客栈(www.devze.com)其它相关文章！