Openapi-specification: Proposal: Default responses for all endpoints

[sebastian-demel]

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

[ralfhandl]

+1

[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]

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.