Smart-doc 3.1.0版本发布：全面提升API文档生成能力

Smart-doc是一款基于Java源代码和注释自动生成API文档的工具，它能够通过解析代码中的注解和注释来生成多种格式的文档，包括HTML、Markdown、Word等。作为一款轻量级、零侵入的文档生成工具，Smart-doc在Java开发者中广受欢迎，特别适合Spring Boot、Dubbo等框架的项目使用。

近日，Smart-doc发布了3.1.0版本，这个版本带来了多项重要改进和新特性，主要集中在枚举类型支持、文档生成优化、请求示例增强等方面。下面我们将详细介绍这个版本的主要更新内容。

枚举类型支持的全面增强

3.1.0版本对枚举类型的支持进行了大幅改进，解决了多个场景下的枚举处理问题：

1. 内部枚举处理：修复了内部枚举类加载失败的问题，现在能够正确处理各种嵌套枚举场景。

2. 枚举示例值生成规则：改进了枚举示例值的生成逻辑，使其更加合理和可配置。新增了enumConvertor配置项，允许开发者自定义枚举值的转换逻辑。

3. 枚举数组处理：修复了枚举数组示例值中引号处理不当的问题，确保生成的JSON格式正确。

4. 请求头枚举支持：现在请求头参数也支持枚举类型，进一步扩展了枚举的应用场景。

5. Map中的枚举处理：修复了当请求参数或响应结果为Map<Enum, Value>时解析不正确的问题。

这些改进使得Smart-doc在处理复杂枚举场景时更加可靠和灵活，为开发者提供了更好的文档生成体验。

文档生成优化与增强

3.1.0版本在文档生成方面也做了多项优化：

1. 示例字段支持：为Markdown文档参数添加了"Example"字段，随后扩展支持到HTML、AsciiDoc和Word格式，使生成的文档更加直观。

2. HTML模板压缩：新增了HTML模板自动压缩功能，减小生成的HTML文件体积，提高加载速度。

3. Dubbo接口Word文档支持：新增了RpcWordDocBuilder，专门用于生成Dubbo接口的Word文档，丰富了文档输出格式的选择。

4. 样式修复：修复了当使用"xt256"样式时窗口显示错误的问题，提升了文档的视觉体验。

这些优化使得生成的文档更加专业、美观，同时也提高了生成效率。

请求处理与验证增强

在请求处理和参数验证方面，3.1.0版本也带来了重要改进：

1. 多部分表单数据处理：修复了当ContentType为multipart/form-data时保留查询参数的问题。

2. 参数文档修正：修正了@RequestBody和无注解表单参数的文档生成问题。

3. 请求示例生成：改进了API文档中请求示例的生成逻辑，使其更加准确和实用。

4. 验证消息占位符解析：新增了对验证消息中占位符的解析支持，能够正确处理如@Size(max = {value}, message = "长度不能超过{value}")这样的注解。

5. 参数最大长度解析：增强了从注解中获取参数最大长度的能力，支持解析常量值。

这些改进使得Smart-doc能够更准确地反映API的实际行为，特别是对于复杂的请求和验证场景。

其他重要改进

除了上述主要特性外，3.1.0版本还包含以下值得关注的改进：

1. JDK17文本块支持：通过升级qdox到2.0.3.5版本，新增了对JDK17文本块的支持。

2. OpenAPI操作ID一致性：使生成的openapi.json文件中的operationId值与springdoc-openapi保持一致，提高了与其他工具的兼容性。

3. 代码质量提升：引入了.editorconfig文件保证代码格式一致性，重构了自定义字段逻辑，优化了API文档生成过程，并加强了Javadoc的严格验证。

4. 依赖项更新：升级了多个依赖项版本，包括beetl、gson、junit-jupiter等，提高了项目的安全性和稳定性。

总结

Smart-doc 3.1.0版本是一个功能丰富、改进全面的更新，特别是在枚举处理、文档生成质量和请求验证方面有了显著提升。这些改进不仅解决了多个已知问题，还引入了实用的新特性，使得Smart-doc作为API文档生成工具更加成熟和强大。

对于现有用户，建议升级到3.1.0版本以获得更好的文档生成体验；对于新用户，这个版本提供了更全面、更稳定的功能，是开始使用Smart-doc的好时机。随着这些改进，Smart-doc继续巩固了其在Java API文档生成领域的领先地位，为开发者提供了高效、准确的文档生成解决方案。