Are there plans to add support for global responses?

[davidkeaveny]

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.

[lornajane]

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.

[karenetheridge]

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.

[miqui]

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:

[lornajane]

Whether we add it to the main specification or not, the feature is currently available in Overlays and it seemed correct to signpost that.

[miqui]

agreed @lornajane . Good callout. I am sometimes conflicted on this kind of choice. Most of the time, I prefer tools that provide a native approach rather than layering an additional tool. Of course, opinions vary.