[Question] Extend/override properties of a parameter

[emauricio]

Hello there, I got a small question about the compoments[parameter]

Currently, im trying to make some parameters reusable and the basic seems pretty simple.

# 
openapi: 3.0.1
info:
  title: An include file to define common parameters
  version: 1.0.0
paths: 
    /test:
      get:
        ...
        parameters:
          - $ref: 'parameters.yml#/components/parameters/reusableParam'
        ...
components:
  parameters:
    reusableParam:
      in: query
      name: reusableParam
      description: filter something
      schema:
        type: number
        default: 30

Now my question is, how can I avoid to duplicate the reusableParam if another path might need the same one but maybe with required: true or different default: 50

what would be the "correct" way to do it?

Thank you in advance.

[emauricio]

Any update about this?
It is quite funny that I end up in my own ticket some months later looking for the same. 😄

[bilak]

This would be very helpful. I'm also defining parameters which differ only with required attribute (true
|false).

[geoffreywiseman]

I have the exact same schema I need to use in three places, I just want to change the top-level description. The schema's the same, the description varies just slightly in ways that are subtly important. So instead of re-using it, I have to duplicate it.

[MikeRalphson]

@geoffreywiseman OAS (or whatever version the next release ends up as being) will support $ref with a sibling description property.

[geoffreywiseman]

OK, now I'm curious about why the next version might not be OAS. ;) Is there somewhere I go to read about that?

[MikeRalphson]

Sorry, there should have been a 3.1 in there, which got lost in editing!

[gfiehler]

I agree and also need this feature, but with the addition of wanting to override the example values on my parameters to be more relevant to each operation. Or the ability to do some type of allOf on parameters where I can include an existing parameter definition and override one or more properties as you can with schemas.

[colin-p-hill]

Also running into a use for this. I've got parameters that are reused across multiple endpoints, but they're sometimes query parameters and sometimes path parameters, depending on whether they're identifying a single resource or filtering a collection of resources.

[osteel]

Yes, same need here. Also not the first time I end up on this thread 😄

So much duplication going on in my OpenAPI definitions, at the moment.

[bansal6432]

I am also feeling the need for the same.
Need to override name and required property for a path parameter.

[danielesegato]

I've another use-case for this

No reuse:

openapi: 3.0.0
components:
  schemas:
    TextContainer:
      type: object
      properties:
        format:
          title: Text Format
          description: Type of formatting of this text.
          type: string
          enum:
          - plain
          - html
          - markdown
          default: plain
        text:
          type: string
      required:
      - text

paths:
  /find:
    get:
      summary: FindTexts
      description: Find specific texts
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: only
          in: query
          required: false
          schema:
            description: Optionally filter a specific text type.
            type: string
            enum:
              - plain
              - html
              - markdown
              - any
            default: any

3 different features I'd like here, please note that:

1. the two usages have different description
2. the two usages have different default
3. the second usage has an additional property "any" compared to the first usage

The way I would like it to work:

openapi: 3.0.0
components:
  schemas:
    TextFormat:
      title: Text Format
      description: Type of formatting of this text.
      type: string
      enum:
        - plain
        - html
        - markdown
    TextContainer:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/TextFormat'
          default: plain
        text:
          type: string
      required:
      - text

paths:
  /find:
    get:
      summary: FindTexts
      description: Find specific texts
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: only
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TextFormat'
            // override
            description: Optionally filter a specific text type.
            enum:
              // some way to tell I want to add to the enum (a similar argument could be done for exclude)
              - $add: [any]
            default: any