OpenAPI-Specification
OpenAPI-Specification copied to clipboard
Proposal: Default responses for all endpoints
I suggest that we add "default responses" that can be defined as default response for All endpoints. This would avoid copy-paste for some common responses like:
429 Too Many Requests 405 Method Not Allowed
The format could be
produces:
- application/json
responses:
'429':
description: to many requests in the given timeframe
schema:
$ref: '#/definitions/error'
paths:
...
Or if flexibility is required, we could alter the default response keyword to take a list of responsedefinitions. This could benefit with the response code range proposal (https://github.com/swagger-api/swagger-spec/issues/516).
responseDefinitions:
"success":
description: request successful
code: 200
"request limit":
description: to many requests in the given timeframe
code: 429, 419
schema:
$ref: '#/definitions/error'
"server error":
description: server error
code: 500 - 599
schema:
$ref: '#/definitions/error'
paths
test:
get:
responses:
default:
- "success"
- "request limit"
- "server error"
this would require some changes to the default response keyword.
:+1: to the suggestion. As you mentioned, this would save A LOT of copy/paste.
Link to meta #566
Just a reminder, please use github reactions, rather than "+1" comments (two recent ones deleted).
Is there any progress with this? The ticket is open for more than 3 years now... :(
I cannot imagine why this is not fixed yet as this issue just makes impossible to specify an error for an invalid path (404) or method (405).
you can reference responses, which is more or less what is being requested here:
paths:
/my_endpoint:
get:
responses:
404:
$ref: "#/components/responses/notFound"
405:
$ref: "#/components/responses/methodNotAllowed"
/other:
get:
responses:
404:
$ref: "#/components/responses/notFound"
405:
$ref: "#/components/responses/methodNotAllowed"
components:
responses:
notFound:
description: "Not found response"
content":
application/json":
schema:
$ref: "#/components/schemas/notFoundResponse"
methodNotAllowed:
description: "Method Not Allowed response"
content":
application/json":
schema:
$ref: "#/components/schemas/methodNotAllowedResponse"
I know this is much more verbose, but at least is a workaround....
+1 dream about this feature
+1, will be useful
+1, amazing feature
+1, I will be gratefull
+1 this will save a lot of repeating docs code
+1 would save a lot of time
+1
this will be usefull
This would be incredibly useful and performance booster!
its so helpfull if this feature is exist
We have about 800 endpoints. Repeating the same error response references everywhere increases the JSON a lot...
I'm also wondering how this isn't a thing yet. There's so many responses that are just part of every single endpoint by default. Things like "content-type not supported", "invalid credentials", "request entity too large", "malformed content", and more... Are we not supposed to add these to the API at all? Or are we really supposed to add these manually to every endpoint?
Also, what about responses that aren't even tied to an endpoint at all? For example, an "endpoint does not exist" response? I obviously can't add that response to any of the endpoint definitions.
Maybe some of those are not supposed to be part of the API definition at all, but I'm using RFC 7807
for my error responses and I want to give a unique response for each error so that clients can switch on the type for error handling. Currently this is a big pain to do.
I'm currently looking at the possible need to add a default / override for the JSON Schema, $schema
$vocabulary
etc keywords in OAS 3.1
A design question comes up between simplicity and extensibility of this "default" feature.
Would something like:
openapi: 3.1.0
info:
title: API
version: 1.0.0
defaults:
responses:
'405':
description: Method not allowed
schema:
$ref: '#/components/responses/error'
'429':
description: Too many requests
schema:
$ref: '#/components/responses/error'
headers:
....
address the requirements for people in this issue? Bearing in mind @darrelmiller's very good advice in this tweet.
+1 for this feature!
I'm interested in that. Similar to what's been discussed so far in https://github.com/OAI/OpenAPI-Specification/issues/563
+1
@MikeRalphson With regards to the tweet: Does the spec already contain some language whether the defined responses should be exhaustive? When manually implementing an API client this information might be gathered from description texts or sources outside the openapi definition, but for code generation it is unclear, I think.
It would be really interesting to know whether people actually need to define common responses for all endpoints, or just some sensible fall-back handling for all kinds of undefined responses. If you like respond with :tada: for default handling would be enough and with :rocket: if having explicit definition for common responses would give you more.
I have an in-progress update to the Overlay specification to suggest enabling this method to apply defaults to an OpenAPI description using an Overlay.
#### Default Overlays Examples
Using wildcards and the `default` action, overlays can be used to provide default behavior.
```yaml
overlay: 1.0.0
info:
title: Provide defaults where objects don't exist
version: 1.0.0
updates:
- target: paths.*.get.responses.400
default:
description: Bad request
content:
application/http-problem:
schema:
$ref: "/components/schemas/badRequestProblem"
- target: paths.*.get.responses.404
default:
description: Not found
content:
application/http-problem:
schema:
$ref: "/components/schemas/notFoundProblem"
- target: paths.*.get.responses.5XX
default:
description: Server Error
content:
application/http-problem:
schema:
$ref: "/components/schemas/serverErrorProblem"
Would there be any way of indicating some default responses as a combination of status code + headers + body? For example 301 + Location, 400 + Content-Type: application/problem+json, 503 + Retry-After.
Common responses with http status codes, schemas, and example, or at least common errors, would be really great to have and would allow to focus endpoint description only on specific success responses and specific, meaningful error responses.
This is a must-have feature, and it's disappointing that the issue was opened back in 2015, and no lead still. Upvote!
you can reference responses, which is more or less what is being requested here:
paths: /my_endpoint: get: responses: 404: $ref: "#/components/responses/notFound" 405: $ref: "#/components/responses/methodNotAllowed" /other: get: responses: 404: $ref: "#/components/responses/notFound" 405: $ref: "#/components/responses/methodNotAllowed" components: responses: notFound: description: "Not found response" content": application/json": schema: $ref: "#/components/schemas/notFoundResponse" methodNotAllowed: description: "Method Not Allowed response" content": application/json": schema: $ref: "#/components/schemas/methodNotAllowedResponse"
I know this is much more verbose, but at least is a workaround....
This is an absolute nonsense, how a declared "GET /my_endpoint" could result in a 404 or 405, these errors only apply to the inverse set of declared endpoints, which is the infinite set of undeclared things.
Adding a global response might make the contract definition much more "implicit" and I get that. On the other hand this feature can be handy for many specific use cases.
For example:
I an developing a platform that generates server API from openAPI contract for developer which in turn will implement the contract.
The web server I use performs some validations on incoming requests (vertx-web-openapi
is the web server).
It would be nice if I can auto add that response to all new endpoints, something some developers using this platform will almost certainly won't, because this error itself is "implicit" in the code.
I am not sure if it is a good/bad idea to have this feature but there might be a solution in between.
+1 Surprised this is not implemented yet, this would save me lots of work