OpenApi: how to describe error codes and messages?

Question

I'd like to provide a series of custom codes and message for my error 400 but can't find any way to do so. Ideally something like:

Error:
  type: object
  enum:
    - [E01, 'Error1']
    - [E02, 'Error2']

And so on

Fils

Answer 1

So I'm not sure that enums here can help you. If you take a look over official documentation Enums are just strings, not object https://swagger.io/docs/specification/data-models/enums/ .

So my proposal is to use :

ErrorType:
 type: object
 properties:
   code: 
     type: integer
   name:
     type: string
 example:   # Sample object
     code: 10
     name: Custom Error

 Error:
  type: object
  properties:
     errors:
       oneOf:
         - $ref '#/ErrorType'
         - etc...
or directly without properties
Error:
  type: object
  oneOf:
   - $ref '#/ErrorType'
   - etc...

You can take a look for more examples on the official page https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

Maudiemaudlin

Answer 2

You can check out how Twitter has described it with $oneOf ( https://api.twitter.com/labs/2/openapi.json ) but unfortunately this convention is not easy nor supported by code generation tools like openapi-generator.

Until OpenApi supports enum descriptions (proposal is pending), one of the easiest ways are to:

1. define enum with all possible error codes
2. in the top level description: section of the spec define an inner section (with markdown notation #Error codes) that lists all error codes along with description.
3. Automated tool should check if the enum and description is consistent.

Sporades

The link is no longer available. In the future, please quote relevant bits of the linked page into your answer for posterity in line with stackoverflow.com/help/how-to-answer. – Postilion