Example of Parameters object reuse

[SensibleWood]

Hello. I can't find an example in the draft specification of Parameters object reuse i.e. when encapsulated by a Component object.

Suggest one is added to the draft specification for clarity and ease-of-use.

Apologies if there's already an issue open for this.

[whitlockjc]

Reusing any component, regardless of type (header, parameter, response, ...) is the same so if you've seen one example, you've seen them all. The way this works is you define the object in #/components/{type} and then where you want to reuse it, you use a Reference Object to point to it. So for example, I might describe my person parameter at #/components/parameters/person and I would reference it elsewhere via {"$ref": "#/components/parameters/person"}.

I'm not saying we shouldn't have an example, just wanting to help you figure this out now instead of waiting on a change.

[SensibleWood]

Thanks. I understood how the $ref is expressed as there's plenty of examples. What I specifically wanted to know was when you implement the reuse in an parameter object. Is it like this?

get:
  parameters:
    - $ref: #/components/parameters/person
    - in: query
      name: another_random_parameter
      type: string

Cheers

[whitlockjc]

Yes, that's exactly right.

[SensibleWood]

Sweet. Thanks!

[whitlockjc]

No problem. I'll keep this open to let the suggestion of having an explicit parameters reference example in the documentation get processed.

[ghost]

IS this the right place to ask about overrides of references? In the example above, person may be defined in: body, but I would like to to re-use it in: formData without defining multiple objects. The second declaration is discarded it it is in the reference. IF so, this would need to be documented, as it is the one I most frequently bump into stopping real re-use of parameters.

[whitlockjc]

What you want to do isn't possible with one parameter definition because you can't use a reference and then override/replace/merge properties into it. Due to OAI not allowing JSON References everywhere, you will have some duplication somewhere. There are a few different ways to approach this, each with its own level of duplication. Below is one example:

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
  parameters:
    FormPerson:
      name: person
      in: formData
      schema:
        $ref: '#/components/schemas/Person'
    BodyPerson:
      name: person
      in: body
      schema:
        $ref: '#/components/schemas/Person'

There are multiple ways to do reuse to help with this.

[ghost]

Ah, I am only used to OAI2 spec without the standardised component section. Your form is indeed more lightweight, but only in OAI3. Good to know this is being addressed in the roadmap, thanks.

[whitlockjc]

You could do the same with 2.0, just using #/parameters instead of #/components/parameters and #/definitions instead of #/components/schemas.

[handrews]

The request to override parameter fields is being tracked as #2026.

This issue is only for tracking the originally requested example.

[handrews]

Given that we haven't seen more complaints about this, and the confusion was likely due to changes from the 2.0 timeframe, I'm going to close this. We can't add an example of every possible use of $ref, and (aside from Path Item, which has other issues tracking it) they're all the same anwyay. Please feel free to re-open / open a new issue if you object.