Is it possible to have different #Ref Based on My API's Version

Hi Marc,

OpenAPI does not have a way to vary payloads based on server variables. The most consumer-friendly approach is to provide separate API definitions for different API versions.

If you want to use a single API definition, you can try one of the following:

1) Remove the version from the server URL and instead define different path versions as separate path items:

paths:
  /v1/something:
    ...
  /v2/something:
    ...

2) Use a single path with oneOf or anyOf to specify the possible schemas:

paths:
  /something:
    post:
      requestBody:
        description: API version 1 uses `ConfigStructure` and version 2 uses `ConfigStructure2`.
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/ConfigStructure'
                - $ref: '#/components/schemas/ConfigStructure2'

2) Use a single ConfigStructure schema containing all properties from all versions, and use the description or extensions to document which properties are required/returned by later versions of the API.

Hi Marc,

Your syntax is correct. This is a limitation of Swagger UI, currently it doesn't automatically generate examples for anyOf/oneOf schemas:

https://github.com/swagger-api/swagger-ui/issues/3803

As a workaround you can provide request and response examples manually:

content:
  application/json:
    schema:
      anyOf:
        - $ref: '#/components/schemas/Foo'
        - $ref: '#/components/schemas/Bar'
    examples:
      ConfigStructure:
        value:
          prop1: value1
      ConfigStructureV3:
        value:
          prop2: value2