Forum Discussion

mbeaudry1's avatar
mbeaudry1
New Contributor
5 years ago

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

Hello, I am new to swagger and using OpenAPI 3 and have come across something I can't find a reference or example to. Might be that I don't know the right key words to look for. Here is a snippit o...
  • HKosova's avatar
    5 years ago

    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.

  • HKosova's avatar
    HKosova
    5 years ago

    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