Definitions for error responses

[mclate]

It's obvious that each api will have a bunch of errors. Each request can usually raise one of several errors (where subsets can differ for different routes).
Current scheme allows only one response with given status code. While this is generally okay for successful responses (like 200 OK, 301 Redirect etc) it doesn't play well with codes above 400. For example, 400 Bad Request can be caused by many reasons, such as missing fields, extra fields, incorrect data or other preconditions. It is required to let client know what errors can he expect for each request and what playload (if any) will each error have.

This all leads to a requirement of having errors (or exceptions) definition.
It can be similar to current responses section, and each request method would have list of errors (exceptions?) that might be raised.

Another useful thing is to have api-wide exceptions. The best examples of such are 401 Unauthorized and 500 Server Error as they can be raised almost by any request.

[conorroche]

+1 for this, in the 1.2 spec as the response messages was a list you could have multiple messages for the same http error code, now in 2.0 as its a dict you cant have that, we use this a lot in our apis e.g.

https://api.car.ma/apidoc/ref/bookings.json

see related swagger-ui issue
swagger-api/swagger-ui#1489

[nicolasxu]

code: 4000, message: ...
code: 4001, message: ...
code: 4002, message: ...

If I want to define the above spec in API response, how should I do it? I think it is not schema, right?

[webron]

If it's just a string, you can only define it as a string. If it has a structure like JSON then yeah, it's a schema.

[nicolasxu]

Schema is just a structure with key and data type for the key, but I need to supply this schema with some instance of filled data. Right now, I am just putting it in description. Is there a better way to do it?

[webron]

Have you seen the examples property?

[nicolasxu]

Thanks for reminding me! examples looks like a better place to put the data. I added example in YAML but it doesn't show up on the compiled UI. Is this the intended behavior?

[webron]

I'm not entirely sure what you mean by compiled UI... Some tools may not support the display of it yet. If you find that's the case, please open an issue on the relevant project.

[nicolasxu]

I mean this

http://editor.swagger.io/#/

will not show examples in responses object. Thank you very much for helping me with this issue!

[webron]

Yeah, I don't think the editor currently renders the examples. Feel free to open a ticket about it on swagger-editor.

[jharmn]

Reviewing other error-related issues, this seems to have a lot in common with #521 and #236 (linked here to provide more perspective).

[jharmn]

Link to meta #566

[handrews]

• This would be done with a oneOf or anyOf schema, just like multiple request body structures under the same media type
• In 3.1 you can use the const keyword in schemas for filled data (at least if I'm interpreting "filled data" correctly)
• Doing anything more structurally significant, like allowing a list of alternatives per code, fits with the Moonwalk project (4.0) in the OAI/sig-moonwalk repository – feel free to join the discussions there!

Since nothing else can be done about this in 3.x, I'm going to mark this "Moved to Moonwalk" and close it.