SpringDoc OpenAPI中@NotEmpty注解的OpenAPI规范生成问题解析

在Spring生态系统中，SpringDoc OpenAPI作为流行的API文档生成工具，其与Jakarta Bean Validation规范的集成一直是开发者关注的重点。近期在2.8.6版本中出现了一个值得注意的行为变化：当使用@NotEmpty注解时，生成的OpenAPI规范不再自动将字段标记为必填(required)，这与Jakarta规范的语义产生了偏差。

问题本质

Jakarta Bean Validation规范中，@NotEmpty注解具有双重约束：

1. 隐式的@NotNull约束（空值无法通过验证）
2. 显式的非空约束（字符串长度/集合大小必须大于0）

在SpringDoc OpenAPI 2.8.5及之前版本中，工具正确地识别了这种双重约束，会在生成的OpenAPI规范中同时体现：

• 将字段加入required数组
• 添加minLength:1或minItems:1约束

但从2.8.6版本开始，这个逻辑发生了变化，导致生成的规范中缺失了required标记，只保留了长度/大小的约束。

技术影响

这种变化带来的主要问题包括：

1. 文档准确性下降：API文档未能完整反映实际的验证规则
2. 客户端代码生成问题：基于不完整规范生成的客户端可能不会执行必要的空值检查
3. 开发体验退化：开发者被迫使用冗余注解组合来维持原有行为

解决方案分析

从技术实现角度看，正确的处理逻辑应该遵循Jakarta规范的语义层次：

@NotEmpty = @NotNull + 非空校验

因此OpenAPI规范的生成应当映射为：

• 对于字符串类型：required:true + minLength:1
• 对于集合类型：required:true + minItems:1

临时解决方案

在当前版本中，开发者可以采用以下方式保持行为一致：

// 方案1：显式组合注解
@NotNull
@NotEmpty
private String field;

// 方案2：使用OpenAPI原生注解
@Schema(required = true)
@NotEmpty 
private String field;

最佳实践建议

1. 对于关键API字段，建议显式使用@NotNull+@NotEmpty组合，确保验证逻辑的明确性
2. 在团队内部建立注解使用规范，保持代码一致性
3. 关注SpringDoc OpenAPI的版本更新，及时获取修复情况

框架设计思考

这个问题反映了API文档生成工具面临的典型挑战：如何在保持与底层规范一致性的同时，提供直观的开发者体验。理想的解决方案应该：

• 尊重原始规范的语义
• 最小化开发者的注解负担
• 保持跨版本的稳定性

希望SpringDoc团队能在后续版本中恢复这一符合直觉的行为，或者至少提供明确的配置选项来控制这种映射逻辑。