告别Swagger！Spring Boot集成Smart-Doc自动生成API文档

程序员云帆哥2025-12-14 9:23

文章目录

- [一、什么是 Smart-Doc？](#一、什么是 Smart-Doc？)
- 二、步骤
- - [1. 添加 Smart-Doc Maven 插件](#1. 添加 Smart-Doc Maven 插件)
  - [2. 创建配置文件 smart-doc.json](#2. 创建配置文件 smart-doc.json)
  - 3.生成文档
  - [4. 查看效果](#4. 查看效果)
  - [5. 官方资源](#5. 官方资源)
- 三、总结

一、什么是 Smart-Doc？

Smart-Doc 是一款基于 Java 源码和注释分析、零注解侵入的 API 文档生成工具。

✅ 无需 @Api、@ApiOperation 等 Swagger 注解

✅ 支持 Spring Boot、Spring MVC、Dubbo 等

✅ 输出格式：HTML、Markdown、Word、OpenAPI、Postman JSON 等

✅ 通过 Maven / Gradle 插件一键生成

目标

在 Spring Boot 项目中集成 Smart-Doc
使用 Maven 插件生成 Markdown 和 HTML 格式的 API 文档
实现无侵入、自动化文档更新

二、步骤

1. 添加 Smart-Doc Maven 插件

在 pom.xml 的中加入：

xml 复制代码

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.3.5</version>
    <configuration>
        <configFile>src/main/resources/smart-doc.json</configFile>
    </configuration>
</plugin>

2. 创建配置文件 smart-doc.json

在 src/main/resources/ 下新建 smart-doc.json：

json 复制代码

{
  "outPath": "E:\\docs",
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "coverOld": true,
  "createDebugPage": false,
  "packageFilters": "com.example.demo.controller.*",
  "responseBodyAdvice": {
    "className": "com.example.demo.result.Result"
  }
}

3.生成文档

在项目根目录执行以下命令：

bash 复制代码

# 生成 HTML（默认）
mvn smart-doc:html

# 生成 Markdown
mvn smart-doc:markdown

# 生成 OpenAPI (Swagger) JSON
mvn smart-doc:openapi

生成的文档位于：E:\docs\index.html

4. 查看效果

打开 E:\docs\index.html，你将看到：

接口分组（按 Controller）
请求方法、URL、参数类型（Path/Body/Query）
请求/响应示例（自动从实体类推导）

5. 官方资源

GitHub: https://github.com/smart-doc-group/smart-doc
官网文档: https://smart-doc-group.github.io/zh/

三、总结

🚀 无需启动应用！Smart-Doc 静态分析源码即可生成。
强烈推荐用 Smart-Doc 替代 Swagger，更简洁、高效、易维护！