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

Smart-doc是一款基于Java源代码和注释自动生成API文档的工具，它能够通过解析代码中的注释和注解，自动生成清晰、规范的API文档，支持多种文档格式输出。作为一款轻量级、零侵入的文档生成工具，Smart-doc在Java开发者社区中广受欢迎。

核心功能增强

本次3.1.1版本带来了多项重要改进，首先是模板引擎的优化。开发团队重构了WordXmlEscape和HtmlEscape类，提升了文档生成过程中的转义处理能力，确保生成的文档在各种环境下都能正确显示特殊字符。同时，通过设置Beetl模板引擎的类加载器，解决了在某些复杂项目结构中可能出现的模板加载问题。

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

验证与类型处理改进

针对参数验证方面，3.1.1版本增加了对默认验证消息占位符的支持，开发者现在可以在验证注解中使用更丰富的消息模板。对于Map类型的处理也进行了优化，修正了键类型检查的错误，确保文档能准确反映Map结构的实际类型信息。

在示例值生成方面，现在会根据字段的实际类型而非总是使用String类型来生成示例值，这使得生成的文档示例更加贴近实际使用场景。同时新增了allowSelfReference配置项，让开发者能够控制是否允许文档中出现自引用类型。

文档生成稳定性提升

本次更新修复了多个可能导致文档生成失败的问题，特别是当响应字段使用特定注解组合时可能出现的错误。开发团队还优化了方法跳过逻辑，新增了判断方法是否应该跳过文档生成的机制，为开发者提供了更精细的控制能力。

开发者体验优化

除了功能改进外，3.1.1版本还完善了项目的贡献指南，新增了中英文版本的贡献规范，明确了代码提交和PR审核流程，为社区开发者参与项目贡献提供了更清晰的指引。同时优化了错误报告描述，使得开发者能够更准确地定位和反馈问题。

总结

Smart-doc 3.1.1版本通过多项功能增强和问题修复，进一步提升了API文档生成的准确性、灵活性和稳定性。无论是核心的文档生成能力，还是对OpenAPI规范的支持，亦或是开发者体验方面，都有了显著改进。这些变化使得Smart-doc在Java生态中的文档生成工具领域继续保持领先地位，为开发者提供更高效、更可靠的API文档解决方案。