kogosoftwarellc / open-api

A Monorepo of various packages to power OpenAPI in node
MIT License
892 stars 235 forks source link

Tips on user-facing error messages? #771

Open danactive opened 2 years ago

danactive commented 2 years ago

My app's frontend is querying my endpoint for form field validation and is displaying the backend error message directly, as this screenshot shows, a regular expression pattern (regex) to the end user:

regex

This is my OpenAPI schema partial definition

mobile:
          type: string
          nullable: true
          format: phoneNumber
          description: Mobile Number for sending SMS
          pattern: ^[1-9]\d{1,14}$
          example: 15551234567

This is the error using errorTransformer

openapiError:

{
  "path": "mobile",
  "errorCode": "pattern.openapi.requestValidation",
  "message": "must match pattern \"^[1-9]\\d{1,14}$\"",
  "location": "body"
}

ajvError:

{
  "instancePath": "/body/mobile",
  "schemaPath": "#/properties/body/properties/mobile/pattern",
  "keyword": "pattern",
  "params": {
    "pattern": "^[1-9]\\d{1,14}$"
  },
  "message": "must match pattern \"^[1-9]\\d{1,14}$\"",
  "location": "body"
}

I don't have any error properties to better craft an error message, best I can do is display ${openapiError.path} is invalid which would display 'mobile is invalid' to the end-user. Does anyone have a better solution?

Ideally I can define a custom property like showUser or use the exiting description OpenAPI doc (YAML or JSON) property

mobile:
          type: string
          nullable: true
          format: phoneNumber
          description: Mobile Number for sending SMS
          pattern: ^[1-9]\d{1,14}$
          example: 15551234567
          showUser: Needs a mobile country code