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

👍 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

fyi, this long-standing issue is addressed in: https://github.com/OAI/moonwalk

Not the way that I understand it… https://datatracker.ietf.org/doc/html/rfc7807 Grammar specifically says you can have additional fields.
On Fri 5 May 2023 at 20:42, Jeremy Fiel @.> wrote: RFC7807 error schema allows reuse of the same schema with the flexibility to apply different messages for each error in your service. You can create infinite examples of every possible error but the schema remains the same. On Fri, May 5, 2023, 14:21 Homa Wong @.> wrote: > that comment has a ... in the example just where it would explain what it > is trying to achieve > > Hi, the ... literally means adding anything specific for that usage. > > Using that example, 400.BadRequest only describes the HTTP Status that it > is a bad request. > i.e. the user pass in something that does not recognized or accepted by > the endpoint. > What could they be? That's specific to every usage. > > e.g. customer-id is missing, item-count can't be negative number, etc. > > Without the ability to use allOf at the response level, > none of the response can be reused when we need to do any customization > tailors to each usage. > > — > Reply to this email directly, view it on GitHub > < #521 (comment) >, > or unsubscribe > < https://github.com/notifications/unsubscribe-auth/AHU7MTK7B7VSUMGITXAZAU3XEVAKPANCNFSM4BV5WOKA > > . > You are receiving this because you commented.Message ID: > @.> > — Reply to this email directly, view it on GitHub <#521 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHCBEMMZ7NETJ2BIAZ7PHBDXEVCZPANCNFSM4BV5WOKA . You are receiving this because you are subscribed to this thread.Message ID: @.>

You might not want to give your your phone number and address publicly on Github?
You're basically doxxing yourself here 🤔
Sorry for hijacking the thread, carry on.

You might not want to give your your phone number and address publicly on Github? You're basically doxxing yourself here 🤔 Sorry for hijacking the thread, carry on.

Thanks for pointing this... that's the problem of answering by email. Fixed now. Thanks!!

I'm not sure why this rather simple proposal sparked so much debate. It only took working with OpenAPI for a few days for me to notice this gap when defining my API.

Nonetheless, it's not clear what the idiomatic way is for dealing with errors that are common to all your paths (401/403 is the simplest example). Defining these for every path just doesn't seem right.

If the spec was solely for documentation, I would say that error types that are truly universal to all your endpoints, and thus not surprising to callers of your API, are not even worth defining in your spec. But omitting errors that your API can return can have negative implications as soon as you start generating type safe clients with your spec.

This proposal is already 8 years old - how can we move it forward?

Would this be covered by the suggested apiResponses and pathResponses in the OpenAPI v4 (aka Moonwalk) Proposal?

@ralfhandl

@ralfhandl yes, I think we can mark this "Moved to Moonwalk" and close it out here (Features added to Moonwalk will be back-ported to 3.x if it makes sense to do so, so there's no need to track it in both repositories).

@andrew-rivera-dev

I'm not sure why this rather simple proposal sparked so much debate.

This is a standards group, debating things that seem simple is practically a requirement 🙃 It's definitely frustrating at times, but I suspect this didn't get into 3.1 partially because there was a bit of a debate about how much we really even want to document all responses, but mostly because we had big things in 3.1 already and no one realized that the spec work would slow down so much afterwards. But it will find some sort of home in 4.0 (Moonwalk). And possibly to some degree in a future 3.x.

Thanks for clarifying!

This is already possible to achieve using allOf. See here:

#563 (comment)

Navigation Menu

Repository navigation

Proposal: Default responses for all endpoints #521

50 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Proposal: Default responses for all endpoints #521

Description

Activity

mrname commented on Dec 31, 2015

jharmn commented on Feb 16, 2016

MikeRalphson commented on Aug 3, 2018

marmax commented on Jun 12, 2019

NoiseByNorthwest commented on Jul 18, 2019

nogates commented on Jul 19, 2019

saturov commented on Jan 16, 2020

avsmirnov567 commented on Jan 16, 2020

r3tam commented on Jan 16, 2020

50 remaining items

piotr-yuxuan commented on Jun 2, 2023

rockymontana commented on Oct 11, 2023

mxmlnglt commented on Oct 16, 2023

andrew-rivera-dev commented on Mar 14, 2024

ralfhandl commented on Mar 14, 2024

handrews commented on Mar 14, 2024

piotr-yuxuan commented on May 29, 2024

xmak commented on Nov 23, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions