如何在OpenAPI中为验证失败配置自定义错误消息？

1. 在OpenAPI定义中添加自定义校验提示 #

如果你的代码是基于OpenAPI规范生成的，可以直接在字段定义里添加自定义扩展属性来指定错误消息，后续在生成的校验逻辑中读取该属性替换默认提示：

MyField:
  description: blablabla
  type: integer
  default: 1
  minimum: 1
  exclusiveMinimum: false
  x-error-message: "MyField的值不能小于1，请输入≥1的整数"

注意：部分代码生成工具需要额外配置才能识别并应用这类自定义扩展属性。

2. 用Spring Validation注解直接指定消息 #

如果是手动编写实体类的场景，直接在字段上使用@Min注解并设置message参数即可：

public class YourRequestEntity {
    @Min(value = 1, message = "MyField的值不能小于1，请输入≥1的整数")
    private Integer myField;

    // getter、setter方法
}

参数校验不通过时，会直接返回这条自定义提示信息。

3. 全局异常处理器统一定制响应 #

如果需要统一管控所有校验异常的返回格式和消息，可以通过Spring的@RestControllerAdvice实现全局异常处理，捕获校验类异常后自定义返回内容：

@RestControllerAdvice
public class GlobalValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleMethodArgumentNotValid(MethodArgumentNotValidException ex) {
        Map<String, String> errorMap = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach(error -> {
            String fieldName = ((FieldError) error).getField();
            // 直接替换为自定义消息，也可根据字段名做不同映射
            errorMap.put(fieldName, "MyField的值不能小于1，请输入≥1的整数");
        });
        return new ResponseEntity<>(errorMap, HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<Map<String, String>> handleConstraintViolation(ConstraintViolationException ex) {
        Map<String, String> errorMap = new HashMap<>();
        ex.getConstraintViolations().forEach(violation -> {
            String fieldPath = violation.getPropertyPath().toString();
            errorMap.put(fieldPath, "MyField的值不能小于1，请输入≥1的整数");
        });
        return new ResponseEntity<>(errorMap, HttpStatus.BAD_REQUEST);
    }
}

这种方式适合需要统一规范所有接口校验错误返回格式的场景。

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