Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow $ref in request body and response content objects #3056

Closed
DavidBiesack opened this issue Oct 20, 2022 · 1 comment
Closed

Allow $ref in request body and response content objects #3056

DavidBiesack opened this issue Oct 20, 2022 · 1 comment
Labels
re-use: ref-everywhere Requests to support referencing in more / all places

Comments

@DavidBiesack
Copy link

I'd like to define an API to allow the client to accept either application/json or application/problem+json for responses; they share the same schema and description. At present, I must copy/paste the Media Type Object each time, rather than define it oncereuse one

That is, I must code:

        '400':
          description: Bad Request
          content:
            application/json:
              description: {My description of the response}
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/problem+json:
              description: {My description of the response}
              schema:
                $ref: '#/components/schemas/problemResponse'

when I'd really like to do is

        '400':
          description: Bad Request
          content:
            application/json:
              description: {My description of the response}
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/problem+json:
               $ref: '#../application~1json'

Maintaining copies is not scalable, especially if one uses Specification Extensions inside the media type object

Each operation's 400 response (or each 422 response, etc) may differ (error descriptions change) so using a $ref for the entire Response Object is not a complete solution.

@handrews handrews added $ref re-use: ref-everywhere Requests to support referencing in more / all places and removed $ref labels Jan 27, 2024
@handrews
Copy link
Member

In 3.1 it's now possible to override description when referencing a Response Object so this use case should be addressed.

For more generally allowing referencing of everything, see #1462

Feel free to open a new issue if there is something that the description-overriding in 3.1 does not fix, and that is too specific to be covered by #1462.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
re-use: ref-everywhere Requests to support referencing in more / all places
Projects
None yet
Development

No branches or pull requests

2 participants