Spring Boot中OpenAPI Generator的minProperties校验不生效解决方法

问题根因 #

• openapi-generator 5.0.1版本的Spring生成器，不会自动为对象级别的minProperties/maxProperties约束生成对应校验逻辑，哪怕已开启useBeanValidation和performBeanValidation配置。
• 标准Bean Validation（JSR-380）本身没有内置针对对象级属性数量的校验注解，该版本生成器没有内置扩展实现，因此不会在生成的模型类上添加对应校验逻辑。
• 当前配置下，生成器只会为单个字段生成字段级别的校验注解（比如@NotNull、@Size），不会处理跨字段/对象级别的必选约束。

适配当前版本的解决方案 #

由于已开启delegatePattern，不需要修改自动生成的代码，直接通过自定义类级校验实现需求，步骤如下：

1. 确认依赖：Spring Boot Web自带Hibernate Validator实现Bean Validation能力，无需额外添加依赖。
2. 自定义“至少一个字段非空”的校验注解：

   @Target({ElementType.TYPE, ElementType.PARAMETER})
   @Retention(RetentionPolicy.RUNTIME)
   @Constraint(validatedBy = AtLeastOneNotEmptyValidator.class)
   public @interface AtLeastOneNotEmpty {
     String message() default "必须至少传入 businessId 或 nonBusinessId 中的一个";
     Class<?>[] groups() default {};
     Class<? extends Payload>[] payload() default {};
     String[] fields();
   }
   

3. 实现校验逻辑：

   public class AtLeastOneNotEmptyValidator implements ConstraintValidator<AtLeastOneNotEmpty, Object> {
     private String[] fields;
     @Override
     public void initialize(AtLeastOneNotEmpty constraintAnnotation) {
       this.fields = constraintAnnotation.fields();
     }
     @Override
     public boolean isValid(Object value, ConstraintValidatorContext context) {
       if (value == null) {
         return false;
       }
       for (String field : fields) {
         try {
           Field declaredField = value.getClass().getDeclaredField(field);
           declaredField.setAccessible(true);
           Object fieldValue = declaredField.get(value);
           if (fieldValue != null && !((String) fieldValue).isBlank()) {
             return true;
           }
         } catch (NoSuchFieldException | IllegalAccessException e) {
           return false;
         }
       }
       return false;
     }
   }
   

4. 在自定义实现的Delegate方法参数上添加注解触发校验：

   @RestController
   public class EntitiesApiDelegateImpl implements EntitiesApiDelegate {
     @Override
     public ResponseEntity<Void> getEntity(
       @AtLeastOneNotEmpty(fields = {"businessId", "nonBusinessId"}) 
       @Valid @ModelAttribute("id") EntityId id
     ) {
       // 业务逻辑
       return ResponseEntity.ok().build();
     }
   }
   

补充说明 #

• 当前的OpenAPI参数定义（style: form、explode: true）和生成器配置逻辑正常，Spring会自动将查询参数businessId、nonBusinessId绑定到EntityId对象的对应属性上。
• 如果需要让生成器自动添加这类校验逻辑，可以自定义openapi-generator的Mustache模板，在模型类生成时自动拼接自定义注解，无需每次手动添加。
• 如果后续升级openapi-generator到更高版本，可以验证新版本是否原生支持minProperties约束的校验注解生成，部分新版本已集成Hibernate Validator的扩展实现，可自动生成对应逻辑。

内容的提问来源于stack exchange，提问作者CeeTee