Smart-Doc高级配置指南：自定义模板与参数优化实战
项目地址: https://gitcode.com/gh_mirrors/smar/smart-doc Smart-Doc是一款基于Java接口源代码分析生成接口文档的工具，完全零侵入。本文将深入探讨如何通过自定义模板和参数优化来提升API文档的质量和开发效率，帮助开发者轻松打造专业级API文档。
为什么需要自定义模板与参数优化？
在日常开发中，默认的API文档样式和内容往往无法满足团队的特定需求。通过自定义模板，你可以将文档风格与公司品牌保持一致；而参数优化则能让文档更清晰、更易读，减少沟通成本。Smart-Doc提供了丰富的配置选项，让这一切变得简单高效。
自定义模板：打造专属文档风格
模板配置基础
Smart-Doc使用Beetl模板引擎来生成文档，你可以通过修改模板文件来定制文档的外观和结构。核心配置类ApiConfig（src/main/java/com/ly/doc/model/ApiConfig.java）提供了设置模板路径的方法。
自定义模板步骤
- 创建模板文件：在项目中创建自定义的Beetl模板文件，例如
custom-api-doc.md.tpl。 - 配置模板路径：通过
ApiConfig的相关方法设置自定义模板路径。 - 绑定模板变量：在模板中使用预定义的变量，如
${name}、${desc}等，这些变量在DocBuilderTemplate（src/main/java/com/ly/doc/builder/DocBuilderTemplate.java）中进行绑定。
常用模板变量
| 变量名 | 描述 |
|---|---|
name | API名称 |
desc | API描述 |
list | API方法列表 |
requestExample | 是否显示请求示例 |
responseExample | 是否显示响应示例 |
参数优化：提升文档质量与效率
核心参数配置
ApiConfig类提供了大量可配置参数，以下是一些常用的优化项：
serverUrl: 设置服务器基础URL，方便测试调用。allInOne: 是否将所有API合并为一个文档，适合小型项目。outPath: 文档输出路径，建议设置为docs/api便于管理。requestExample和responseExample: 控制是否生成请求/响应示例，默认为true。
高级参数优化
- 递归深度限制：通过
setRecursionLimit(int)方法设置对象递归解析的深度，避免因嵌套过深导致文档冗长。 - 枚举处理：设置
inlineEnum=true可将枚举值内联显示在参数说明中，提高可读性。 - 自定义响应结构：使用
setResponseBodyAdvice(BodyAdvice)自定义统一响应格式。
ApiConfig config = new ApiConfig();
config.setRecursionLimit(5); // 设置递归深度为5
config.setInlineEnum(true); // 内联显示枚举
config.setResponseBodyAdvice(new CustomResponseBodyAdvice()); // 自定义响应处理
全局参数设置
通过setRequestHeaders和setRequestParams方法可以设置全局请求头和参数，避免在每个接口中重复定义。
config.setRequestHeaders(
new ApiReqParam("Authorization", "string", "认证令牌", true)
);
实战案例：构建个性化API文档
步骤1：配置ApiConfig
ApiConfig config = new ApiConfig();
config.setProjectName("用户管理系统API");
config.setAllInOne(true);
config.setOutPath("docs/api");
config.setStyle("dark"); // 使用深色主题
config.setRequestExample(true);
config.setResponseExample(true);
步骤2：自定义模板
创建custom-api-doc.md.tpl模板文件，添加公司Logo和自定义样式：
<div style="text-align: center;">
<h1>${projectName}</h1>
<p>生成时间：${createTime}</p>
</div>
{{for api in apiDocList}}
## ${api.name}
${api.desc}
{{for method in api.list}}
### ${method.name}
{{method.desc}}
{{/for}}
{{/for}}
步骤3：生成文档
通过ApiDocBuilder（src/main/java/com/ly/doc/builder/ApiDocBuilder.java）生成文档：
ApiDocBuilder.buildApiDoc(config);
常见问题与解决方案
模板不生效
确保模板路径配置正确，并且模板文件存在。可以通过开启调试模式config.setTornaDebug(true)来排查问题。
文档生成速度慢
尝试减少递归深度或排除不必要的包：
config.setPackageExcludeFilters("com.example.test");
枚举值未正确显示
检查是否设置了inlineEnum=true，并确保枚举类有正确的注释。
总结
通过自定义模板和参数优化，Smart-Doc可以生成满足各种需求的高质量API文档。无论是调整文档样式、优化内容结构，还是添加个性化元素，Smart-Doc都提供了灵活的配置选项。希望本文能帮助你更好地利用Smart-Doc，提升API文档的质量和开发效率。
如果你有任何问题或建议，欢迎参与项目贡献，共同完善Smart-Doc。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
