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.

[styxlab]

@lornajane Thanks for reporting on the current plans and for mentioning alternative solutions.

I am curious why you are not considering it for future OpenAPI versions as the concept of having some global definitions is already present with the servers object. Therefore, the concept is not new to the spec and it would have many benefits:

• the spec is easier to read
• the spec can be smaller in size
• it will guide code generators to make more re-usable standard code
• the spec is easier to create and maintain

This is a use case that every team is facing when designing OpenAPI specs, so it would also have a high impact.

I also looked in the Overlay Spec and I think it is only a partial solution to the problem. You can use the Overlay to generate a generic error code on every endpoint. That way you save some manual labor. But the result will still be a bloated OpenAPI Spec file where the error code is added to every endpoint instead of having a global section with common error codes.

I am curious to hear your thoughts on this.

[handrews]

@styxlab the existing "global"-ish things such as the Servers Object are problematic for document processing. Or, rather, because of such things, there are about 9 or 10 different ways you have to figure out how to connect pieces of an OpenAPI Description to each other, which is a frustrating amount of complexity for implementors.

In the 3.x series, we are exploring how to best support such things in a way that lets us reduce that complexity in a future 4.0. Right now all of the solutions are unsatisfactory in various ways.

Rather than continue to throw in more OAS-specific complexity, we are trying to leverage the fact that we have an ecosystem of specifications. In particular, we are looking at how to better integrate the OAS and Overlays (#5120), including possibly incorporating Overlays directly so that they can be leveraged for global support within the OAS.

There's a lot to work out there, please feel free to join that discussion. There may need to be changes to Overlays as well to address all of the use cases.