Smart-Doc 的简单使用

1. 简介

smart-doc是一款支持JAVA REST API、JAVA WebSocket、Apache Dubbo RPC和gRPC接口文档生成的工具。

smart-doc率先提出了基于Java泛型定义来推导接口文档的概念。它完全依赖于接口的源代码进行分析和生成文档，无需在业务代码中添加任何注解。只需按照JavaDoc的标准编写注释，smart-doc就能够帮助您生成简洁明了的Markdown、HTML5、Postman Collection 2.0+ 和 OpenAPI 3.0+ 格式的文档。

Smart-Doc无侵入式的API接口文档生成器地址：smart-doc-group.github.io/zh/

2. 引入

这里我主要基于IDEA进行使用。

我们这个项目是SpringBoot多模块项目，下面介绍下引入过程。

根目录的build.gradle文件上添加

groovy 复制代码

plugins {
    id 'com.ly.smart-doc' version '3.0.0'
}

在需要引入smart-doc的模块的build.gradle文件上添加

groovy 复制代码

apply plugin: 'com.ly.smart-doc'

在需要引入smart-doc的模块的resources目录下添加smart-doc.json文件

json 复制代码

{
  "projectName": "XXX平台对内接口文档 - vX.X.X",
  "allInOne": true,
  "outPath": "D:\doc\management",
  "coverOld": true,
  "packageFilters": "com.xxx.xxx.management.controller.*",
  "showAuthor": false,
  "inlineEnum": true,
  "allInOneDocFileName": "index.html",
  "requestExample": "true",
  "responseExample": "true",
  "revisionLogs": [
    {
      "version": "v1.0.0",
      "revisionTime": "2026-06-01",
      "status": "已发布",
      "author": "张三",
      "remarks": "项目初始化版本"
    },
    {
      "version": "v1.1.0",
      "revisionTime": "2026-06-18",
      "status": "已发布",
      "author": "李四",
      "remarks": "XXXXXXXX"
    }
  ],
  "errorCodeDictionaries": [
    {
      "enumClassName": "com.xxx.xxx.common.data.error.CommonErrorCode",
      "codeField": "code",
      "descField": "message"
    },
    {
      "enumClassName": "com.xxx.xxx.management.error.ManagementErrorCode",
      "codeField": "code",
      "descField": "message"
    }
  ],
  "dataDictionaries": [
    {
      "enumClassName": "com.xxx.xxx.common.data.constant.AccountStatusEnum",
      "codeField": "code",
      "descField": "zhDesc"
    },
    {
      "enumClassName": "com.xxx.xxx.common.data.constant.AllocateFlagEnum",
      "codeField": "code",
      "descField": "zhDesc"
    },
    {
      "enumClassName": "com.xxx.xxx.common.data.constant.AsyncOperationEnum",
      "codeField": "code",
      "descField": "zhDesc"
    }
  ],
  "responseBodyAdvice": {
    "className": "com.xxx.xxx.common.web.result.Result"
  }
}

引入后，IDEA右上角Gradle刷新后会在对应模块目录看到下面的菜单：

2.1. 专用工具集成

这些选项生成的文档格式，是为了方便与特定的开发、测试工具联动。

smartDocOpenApi ：生成 OpenAPI 3.0+ 格式的文档。这是一种标准的 API 描述规范，生成后可以导入到 Swagger UI、YApi 等支持该规范的工具中展示和调试。
smartDocPostman ：生成 Postman Collection 2.0+ 文件。可以将这个 JSON 文件直接导入 Postman，从而快速生成接口请求，方便进行接口调试。

2.2. 基础文档格式生成

这些选项用于生成不同格式的离线文档文件，方便本地阅读或分享。

smartDocRestAdoc ：为 RESTful API 生成 AsciiDoc 格式文档。
smartDocRestHtml ：为 RESTful API 生成美观的 HTML 格式文档。
smartDocRestMarkdown ：为 RESTful API 生成 Markdown 格式文档。
smartDocRpcAdoc ：为 RPC 接口 （如 Apache Dubbo）生成 AsciiDoc 格式文档。
smartDocRpcHtml ：为 RPC 接口 （如 Apache Dubbo）生成美观的 HTML 格式文档。
smartDocRpcMarkdown ：为 RPC 接口 （如 Apache Dubbo）生成 Markdown 格式文档。

2.3. 文档管理平台推送

这些选项用于将文档自动推送到在线的文档管理平台，实现团队协作和集中管理。

tornaRest ：将 RESTful API 文档自动推送 到 Torna 企业级接口文档管理平台。
tornaRpc ：将 RPC 接口 文档自动推送 到 Torna 平台。

Torna 是一个功能强大的开源平台，支持文档的集中管理、版本控制和团队协作。与 Smart-Doc 配合，可以实现"代码即文档"的理念。

2.4. 特殊说明

javadoc ：这个选项代表 Smart-Doc 的工作基础，即解析你写的标准 Javadoc 注释。它本身不是一个生成目标，而是 Smart-Doc 分析源码、提取信息的核心方式。

3. 使用

注意在代码中规范书写注释。

文档生成步骤：

执行 smartDocRestHtml 命令
在指定位置会生成 HTML 接口文件。
将 HTML 文件转换为 PDF 文件。

HTML 文件转换为 PDF 文件的方式：在浏览器中打开HTML文件或网页 → 按 Ctrl+P（Windows）或 Cmd+P（Mac）或直接找到打印 → 选择打印机为"另存为PDF" → 保存即可。

上面是生成了PDF格式文档，方便发给客户。

目前体验下来，感觉HTML格式的会更美观。