Smart-Doc 3.1.1版本发布：API文档生成工具的重大升级

Smart-Doc是一款基于Java源代码分析的API文档生成工具，它能够自动从代码注释中提取信息并生成多种格式的API文档。相比于传统的Swagger等工具，Smart-Doc不需要在代码中添加注解，而是直接解析源代码和注释，这使得它更加轻量级且对代码无侵入性。

核心功能增强

本次3.1.1版本在文档生成的核心功能上做了多项重要改进。首先是对Word和HTML文档中特殊字符的转义处理进行了重构，新的WordXmlEscape和HtmlEscape类提供了更健壮的处理机制，确保生成的文档在各种环境下都能正确显示特殊字符。

在OpenAPI规范支持方面，新增了AbstractOpenApiBuilder抽象类，为开发者提供了更灵活的OpenAPI规范生成方式。同时，现在可以根据方法描述或包名自动生成API标签，使得生成的OpenAPI文档结构更加清晰合理。

验证与示例生成优化

针对参数验证的支持，本次更新增加了对默认验证消息占位符的支持。这意味着当开发者使用验证框架（如Hibernate Validator）时，Smart-Doc能够更准确地解析和展示验证规则和错误消息。

在示例值生成方面，修复了之前总是生成字符串类型示例的问题。现在Smart-Doc会根据字段的实际类型生成合适的示例值，例如对于数值类型会生成数字示例，对于布尔类型会生成true/false示例，这使得生成的文档示例更加贴近实际使用场景。

引用处理与配置增强

对于复杂的数据模型，Smart-Doc新增了allowSelfReference配置项，允许开发者控制是否允许模型自引用。这在处理树形结构或图状数据结构时特别有用，开发者可以根据需要选择是否展开自引用关系。

在方法过滤方面，新增了判断方法是否应该被跳过文档生成的能力。这使得开发者可以更灵活地控制哪些方法需要生成文档，哪些方法应该被排除在外，特别适合处理内部方法或框架自动生成的方法。

问题修复与稳定性提升

本次版本修复了多个关键问题，包括Map类型键类型检查错误、响应字段使用泛型时文档生成错误等问题。这些修复显著提升了工具在处理复杂Java类型时的稳定性和准确性。

在模板处理方面，改进了Beetl模板的类加载机制，确保在不同环境下模板都能正确加载和渲染。同时优化了错误报告描述，使得当文档生成出现问题时，开发者能够更快速准确地定位问题原因。

总结

Smart-Doc 3.1.1版本通过多项功能增强和问题修复，进一步巩固了其作为轻量级API文档生成工具的地位。新版本在OpenAPI规范支持、验证消息处理、示例值生成等方面都有显著改进，同时提升了工具的稳定性和灵活性。对于追求代码整洁、希望减少注解污染的Java开发者来说，Smart-Doc无疑是一个值得考虑的API文档解决方案。