Proposal: Default responses for all endpoints

[sebastiandemel]

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.

[mrname]

:+1: to the suggestion. As you mentioned, this would save A LOT of copy/paste.

[jharmn]

Link to meta #566

[MikeRalphson]

Just a reminder, please use github reactions, rather than "+1" comments (two recent ones deleted).

[marmax]

Is there any progress with this? The ticket is open for more than 3 years now... :(

[NoiseByNorthwest]

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).

[nogates]

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....

[saturov]

+1 dream about this feature

[avsmirnov567]

+1, will be useful

[artem-zaitsev]

+1, amazing feature

[ozh-dev]

+1, I will be gratefull

[alexcambose]

+1 this will save a lot of repeating docs code

[Metroxe]

+1 would save a lot of time

[matthiassb]

+1

[malotho-zz]

this will be usefull

[erdimeola]

This would be incredibly useful and performance booster!

[baguse]

its so helpfull if this feature is exist

[Havunen]

We have about 800 endpoints. Repeating the same error response references everywhere increases the JSON a lot...

[Blacklands]

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.

[MikeRalphson]

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.

[devdilson]

+1 for this feature!

[mxmlnglt]

I'm interested in that. Similar to what's been discussed so far in https://github.com/OAI/OpenAPI-Specification/issues/563

[omgkotofey]

+1

[bodograumann]

@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.

[darrelmiller]

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"

[karenetheridge]

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.

[piotr-yuxuan]

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.

[ginosian]

This is a must-have feature, and it's disappointing that the issue was opened back in 2015, and no lead still. Upvote!

[NoiseByNorthwest]

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.

[iekdosha]

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.

[ronaldwanink]

+1 Surprised this is not implemented yet, this would save me lots of work