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

[handrews]

@9ao9ai9ar as you can see in #3528 and #3529, we do intend to stick with semantic versioning. 3.1 was a very complex situation with no good option for compatibility, but it was also for a very specific reason which is not going to be a problem in the future.

3.0.4 and 3.1.1 should be out within a couple of months, and there will be a 3.2 (strictly compatible with 3.1, and with a small amount of enhancements that should make it fairly quick to implement) before there will be a 4.0. We are looking at trying out 4.0 ideas in the 3.x series, so it's possible that shipping "Moonwalk" in 2024 will actually look like shipping incremental 3.x releases containing Moonwalk ideas rather than shipping a full 4.0 within the next few months. It's very up in the air as of this week.

Some things in 3.0.4 and 3.1.1 are specifically about clarifying requirements that come from other specificaitons on which the OAS depends.

BTW, $id and $schema are supported in 3.1 OpenAPI documents. If a tool does not support them, you should lobby the tooling vendor.

[handrews]

@9ao9ai9ar I forgot to answer your initial question - yes, at least some use cases can be handled by $dynamicRef and $dynamicAnchor. In 3.1.1, we've added a section on how this construct can be used for generic types. It's our hope that calling out a clear use case will motivate more tooling vendors to support it, especially because support for generic types has been requeseted many times (there were at least 5 open issues for it that I closed with 3.1.1).

[9ao9ai9ar]

@handrews Looking forward to the 3.0.4 and 3.1.1 publications! I like the idea of doing incremental releases; even though OpenAPI still feels lacking in some areas, I think what we currently have in 3.1, if fully supported by available tools and documented clearly, is powerful enough to meet most requirements.

About $id and $schema, thank you for confirming that they are supported in OpenAPI 3.1, but it'll take some time for outdated information to decay into oblivion :). I only meantioned them because they appear in most examples using $dynamicRef/$dynamicAnchor, and I think no one has explained the background necessary for understanding these features better than Juan Cruz Viotti's blog post.

I also have a need for generic types for a personal project I'm working on right now. Sadly, the tool I use is awesome in every way except not supporting $dynamicRef/$dynamicAnchor and YAML merge keys, the only two methods I know that should be able to achieve my goal, but fortunately, the lack of support is not really a blocker for me.

[guizoxxv]

I believe you could do:

openapi: 3.0.1
info:
  title: An include file to define common parameters
  version: 1.0.0
paths: 
    /test:
      get:
        parameters:
          - $ref: 'reusableParam.yaml'
        responses:
          200:
            description: OK
    /test-2:
      get:
        parameters:
          - name: reusableParam
            allOf:
              - $ref: 'reusableParam.yaml'
              - required: true
              - schema:
                type: number
                default: 50
        responses:
          200:
            description: OK

And in another file reusableParam.yaml:

name: reusableParam
in: query
description: filter something
schema:
  type: number
  default: 30

[handrews]

@guizoxxv allOf is a JSON Schema keyword and only usable inside of a Schema Object

[guizoxxv]

@guizoxxv allOf is a JSON Schema keyword and only usable inside of a Schema Object

@handrews It seems to work when I run npm run dev on a local file in swagger-ui, but indeed it does not work when I try it in https://editor.swagger.io/.