Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings
Discussion options

It would be helpful if OpenAPI specification allowed me to specify certain responses that will be returned for every endpoint in the specification, rather than having to document every response on every endpoint. (Although I would imagine people might want to apply those default responses to some sort of pattern matching, either by path or tag or other...)

For instance, if my API requires authentication on every endpoint, applies rate limiting to every endpoint, and can return a 500 Internal Server Error for every endpoint, then it would be nice to define a default set of responses for 401, 403, 429 and 500. Those responses would also include e.g. rate limit headers.

When following a design-first approach, this would significantly reduce the amount of copy-pasting of response references, reduce the chance of making errors, and reduce size of a fully-documented OpenAPI specification, which then decreases the resources required to process one when generating client-side docs.

You must be logged in to vote

Replies: 2 comments · 1 reply

Comment options

There are no plans to support this in the 3.x specification series, but it's a fairly common use case. The Overlay standard supports this pattern pretty well, and I'd recommend you look at that for a solution.

You must be logged in to vote
0 replies
Comment options

I believe this came up as a moonwalk discussion -- the idea of having global responses for various response codes like 500, 503 which would apply to all endpoints in the document unless they were overridden at a specific operation level, much as we have a global servers object which defines server url prefixes which apply to all operations if not individually overridden.

As it is a new concept that doesn't change existing parts of the document, it could conceivably be added in a 3.x release.

You must be logged in to vote
1 reply
@miqui
Comment options

I agree with @karenetheridge . No disrespect to the overlay spec, but why should I have to use it to describe such a common use case. This would be a relatively easy win. Add this under components:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
4 participants
Morty Proxy This is a proxified and sanitized view of the page, visit original site.