如何在Swagger中自定义REST API请求字段验证错误消息？

直接在Swagger/OpenAPI定义里利用扩展字段覆盖默认的正则校验错误消息，无需修改Java代码，具体分两种版本实现：

OpenAPI 3.x 示例 #

如果使用OpenAPI 3.0+规范，可通过x-error-message扩展字段定义友好提示（SpringFox等主流Swagger实现均支持该扩展）：

openapi: 3.0.3
paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phoneNumber:
                  type: string
                  pattern: '^1[3-9]\d{9}$'
                  # 自定义友好错误消息，替换默认的正则提示
                  x-error-message: '手机号格式不正确，请输入11位中国大陆有效手机号'
              required: [phoneNumber]
      responses:
        '200':
          description: 用户创建成功

Swagger 2.0 示例 #

若仍在使用Swagger 2.0规范，写法类似，同样通过扩展字段定义：

swagger: '2.0'
paths:
  /users:
    post:
      parameters:
        - in: body
          name: user
          required: true
          schema:
            type: object
            properties:
              email:
                type: string
                pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
                x-error-message: '邮箱格式不正确，请输入有效的邮箱地址'
            required: [email]
      responses:
        200:
          description: 用户创建成功

注意事项 #

• 不同Swagger工具对扩展字段的支持可能略有差异，比如部分工具支持validationMessage而非x-error-message，需结合你使用的具体框架（如SpringFox、OpenAPI Generator）的官方文档调整字段名。
• 若当前Swagger实现不支持扩展字段，再考虑作为备选方案：在Java代码中添加@RestControllerAdvice全局异常处理器，捕获MethodArgumentNotValidException，重写错误消息后返回400响应。

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