胖厨胡学斌1. smart-doc 在 SpringBoot 项目中的集成实践
作为一名长期奋战在 Java 后端开发一线的工程师，我深知 API 文档维护的痛苦。传统的手写文档方式不仅效率低下，还经常出现文档与代码不同步的情况。smart-doc 的出现彻底改变了这一局面，它通过解析代码注释自动生成文档，真正实现了"代码即文档"的理念。
smart-doc 与其他文档工具最大的区别在于它的零侵入性。我们不需要在代码中添加任何特殊注解，只需按照标准的 Java 注释规范编写注释，smart-doc 就能自动识别并生成规范的 API 文档。这种方式既保持了代码的整洁，又确保了文档的准确性。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与基础集成
2.1 项目环境要求
在开始集成 smart-doc 前，请确保你的开发环境满足以下要求：
- JDK 1.8 或更高版本
- Maven 3.5+
- Spring Boot 2.x 项目
- IDE（推荐使用 IntelliJ IDEA）
2.2 Maven 插件配置
在项目的 pom.xml 文件中添加 smart-doc 插件配置是最关键的一步。以下是详细的配置说明：
xml复制<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.6.4</version>
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>${project.name}</projectName>
<!-- 是否跳过生成文档 -->
<skip>false</skip>
<!-- 指定Java源码路径 -->
<sourcePaths>
<path>src/main/java</path>
</sourcePaths>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
注意：在实际项目中，建议将 projectName 替换为你的项目名称，可以使用 Maven 属性 ${project.name} 来自动获取项目名。
2.3 配置文件创建
在 src/main/resources 目录下创建 smart-doc.json 文件，这是 smart-doc 的核心配置文件。初始配置可以非常简单：
json复制{
"serverUrl": "http://localhost:8080",
"outPath": "./target/smart-doc",
"projectName": "示例项目"
}
3. smart-doc 高级配置详解
3.1 基础配置优化
一个生产环境可用的配置通常需要包含更多细节：
json复制{
"serverUrl": "http://api.example.com",
"pathPrefix": "/api/v1",
"isStrict": false,
"allInOne": true,
"outPath": "./docs/apidoc",
"coverOld": true,
"createDebugPage": true,
"packageFilters": "com.example.controller.*",
"projectName": "用户管理系统 API",
"style": "light",
"showAuthor": true,
"requestExample": true,
"responseExample": true
}
3.2 多环境支持配置
在实际开发中，我们通常需要区分不同环境的 API 地址：
json复制{
"serverEnv": {
"开发环境": "http://dev.example.com",
"测试环境": "http://test.example.com",
"生产环境": "http://api.example.com"
},
"defaultServerEnv": "开发环境"
}
3.3 数据字典与自定义字段
smart-doc 支持定义数据字典和自定义响应字段，这对于统一项目规范非常有帮助：
json复制{
"dataDictionaries": [
{
"title": "订单状态",
"enumClassName": "com.example.enums.OrderStatus",
"codeField": "code",
"descField": "description"
}
],
"customResponseFields": [
{
"name": "code",
"desc": "响应码",
"ownerClassName": "com.example.common.Result",
"value": "0"
}
]
}
4. 代码注释规范与最佳实践
4.1 控制器注释规范
要让 smart-doc 生成完整的 API 文档，控制器的注释需要遵循特定格式：
java复制/**
* 用户管理控制器
*/
@RestController
@RequestMapping("/api/user")
public class UserController {
/**
* 创建用户
* @param user 用户信息
* @return 创建结果
*/
@PostMapping
public Result<User> createUser(@RequestBody User user) {
// 实现代码
}
/**
* 获取用户列表
* @param page 页码
* @param size 每页数量
* @return 用户列表
*/
@GetMapping
public Result<Page<User>> listUsers(
@RequestParam(defaultValue = "1") int page,
@RequestParam(defaultValue = "10") int size) {
// 实现代码
}
}
4.2 实体类注释规范
实体类的注释会直接影响文档中参数的描述：
java复制/**
* 用户实体
*/
public class User {
/**
* 用户ID
*/
private Long id;
/**
* 用户名
*/
@NotNull
private String username;
/**
* 密码
*/
@Size(min = 6, max = 20)
private String password;
// getters and setters
}
5. 文档生成与使用技巧
5.1 生成文档的多种方式
- 使用 Maven 命令生成：
bash复制mvn smart-doc:html
- 在 IDEA 中直接运行插件：
- 打开 Maven 面板
- 找到 Plugins → smart-doc
- 双击 html 目标
- 配置在构建过程中自动生成：
xml复制<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
5.2 文档生成的高级选项
smart-doc 支持生成多种格式的文档，可以通过修改插件配置来实现：
xml复制<executions>
<execution>
<goals>
<!-- 生成HTML文档 -->
<goal>html</goal>
<!-- 生成Markdown文档 -->
<goal>markdown</goal>
<!-- 生成Word文档 -->
<goal>word</goal>
</goals>
</execution>
</executions>
6. 常见问题与解决方案
6.1 IDEA 中 "Command line is too long" 错误
这是一个常见问题，解决方法如下：
- 打开项目目录下的 .idea/workspace.xml 文件
- 找到
部分 - 添加或修改以下配置：
xml复制<property name="dynamic.classpath" value="true" />
6.2 文档生成不全的问题排查
如果发现生成的文档缺少某些接口，可以按照以下步骤排查：
- 检查 packageFilters 配置是否正确
- 确保控制器类和方法有正确的注释
- 查看 Maven 构建日志是否有错误
- 尝试增加日志级别：
json复制{
"logLevel": "debug"
}
6.3 与 Swagger 的兼容性问题
smart-doc 可以与 Swagger 共存，但需要注意：
- 如果使用 Swagger 注解，需要在配置中开启：
json复制{
"showJavaType": true,
"displayActualType": true
}
- 建议统一使用一种风格的注释，避免混用导致文档不一致
7. 高级特性与定制化
7.1 自定义模板
smart-doc 允许使用自定义模板来改变文档的外观：
- 创建模板文件：
code复制src/main/resources/smart-doc/template/
├── css/
│ └── custom.css
└── html/
└── custom.html
- 在配置中指定模板：
json复制{
"customStyle": "template/css/custom.css",
"customBody": "template/html/custom.html"
}
7.2 API 文档推送
smart-doc 支持将生成的文档推送到 Torna 等文档管理系统：
- 首先配置 Torna 相关信息：
json复制{
"tornaConfig": {
"appToken": "your_app_token",
"appKey": "your_app_key",
"secret": "your_secret",
"openUrl": "http://torna.example.com/api"
}
}
- 使用以下命令推送：
bash复制mvn smart-doc:torna-rest
7.3 与 CI/CD 集成
将 smart-doc 集成到持续集成流程中可以确保文档始终最新：
yaml复制# GitHub Actions 示例
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up JDK
uses: actions/setup-java@v2
with:
java-version: '11'
distribution: 'temurin'
- name: Build with Maven
run: mvn compile smart-doc:html
- name: Upload documentation
uses: actions/upload-artifact@v2
with:
name: api-docs
path: target/smart-doc
8. 性能优化与最佳实践
8.1 大型项目的优化策略
对于包含大量接口的项目，可以采取以下优化措施：
- 分模块生成文档：
json复制{
"moduleList": [
{
"name": "用户模块",
"packageFilters": "com.example.user.*"
},
{
"name": "订单模块",
"packageFilters": "com.example.order.*"
}
]
}
- 使用增量生成：
json复制{
"incremental": true,
"incrementalBuildOnlyModified": true
}
8.2 文档质量控制
确保生成的文档质量需要注意以下几点：
- 统一注释风格
- 为每个参数添加详细说明
- 为接口添加示例值
- 定期检查生成的文档是否完整
8.3 团队协作规范
在团队中使用 smart-doc 时，建议制定以下规范：
- 注释必须包含接口功能描述
- 所有参数必须有说明
- 复杂接口需要提供示例
- 定期检查生成的文档
- 将文档生成纳入代码审查流程
在实际项目中，我发现将 smart-doc 的生成作为 CI 流程的一部分，可以确保文档始终与代码保持同步。同时，通过自定义模板，我们能够生成符合公司风格的 API 文档，大大提高了团队协作效率。