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

文章目录

    • [一、什么是 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. 官方资源

三、总结

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

相关推荐
文丑颜不良啊27 分钟前
LeetCode3101~3120题目解析
java·leetcode
Resean022344 分钟前
SpringMVC 6+源码分析(十一)视图渲染与异步请求(收尾篇)
java·spring·springmvc
靠沿1 小时前
MySQL数据库进阶——存储过程和触发器
java·数据库·mysql
码少女2 小时前
MySQL--库与表的增删改查基础
java·数据库·mysql
Flynt4 小时前
掘金热文说 Spring Boot 4.1 默认开虚拟线程,我实测后发现了更狠的坑
java·spring boot·性能优化
Resean02235 小时前
Spring 源码分析(一)IOC 容器总览与 refresh() 全景
java·后端·spring
保利威视频SaaS小张5 小时前
企业直播接入笔记 12|企业内训直播怎么做签到和学时统计,防挂机这件事比想象中难
java·前端·数据库·笔记·视频云·polvy·polyv
顧棟7 小时前
【ES实战】 索引模板「可追溯、可校验」:一种模板治理的工程化思路
java·数据库·elasticsearch
玄昌盛不会编程8 小时前
LeetCode——2243. 计算字符串的数字和
java·算法·leetcode
文丑颜不良啊8 小时前
LeetCode3061~3080题目解析
java·leetcode