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.

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

[saturov]

+1 dream about this feature