Swagger docs - multiple error codes for a single http response

Question

I'm trying to document a model that always returns a custom response code and associated description. For a single HTTP response code, there could be multiple custom response codes. For example, a 400 response might include:

+===========+======+=============+
| HTTP Code | Code | Description |
+===========+======+=============+
|       400 |    1 | Error 1     |
+-----------+------+-------------+
|       400 |    2 | Error 2     |
+-----------+------+-------------+
|       400 |    3 | Error 3     |
+-----------+------+-------------+

I could document that a 400 status returns an "Error" object that has "Code" and "Description". But I'd like to include all of the custom status codes in the documentation if that's even possible. Is it possible? If so, how would I go about doing this?

are you looking for this? look at the approved answer as well https://stackoverflow.com/questions/36576447/swagger-specify-two-responses-with-same-code-based-on-optional-parameter — turivishal, Jul 28 '20 at 05:59
I don't think it's the same thing I'm looking for, unless I have to document separate schemas for each custom status code. I basically need to specify multiple examples for each http status code — user1795832, Jul 28 '20 at 14:33
Using openapi 3.0 in the Swagger yaml let's me use multiple examples which almost let's me do what I want without a ton of extra work. The only problem is...all of my responses are in XML. In order to provide multiple examples that can't be represented in JSON, you have to put XML in a string literal. I really want to avoid doing that. — user1795832, Jul 29 '20 at 18:32

score 3 · Answer 1 · answered Oct 21 '21 at 23:18

For anyone facing this problem nowadays, here's how I was able to solve it:

              '422':
                description: 'Unprocessable Entity'
                content:
                    application/json:
                        schema:
                          oneOf:
                            - $ref: '#/components/schemas/SchemaForErrror1'
                            - $ref: '#/components/schemas/SchemaForErrror2'

                        examples:
                          Error1:
                            $ref: '#/components/examples/ExampleForError1'
                          Error2:
                            $ref: '#/components/examples/ExampleForError2'

Swagger docs - multiple error codes for a single http response

1 Answers1