How to version Swagger models?

Viewed 133

I have a domain model that contains a number of classes of things, such as Apples, Oranges and Lemons. For example, showing only Apples:

# version 1
Apple: 
  type: object
  required:
    - id
    - name
  properties:
    id:
      type: integer
    name:
      type: string

At a later date I want to add a field to Apple:

# version 2
Apple: 
  type: object
  required:
    - id
    - name
    - variety
  properties:
    id:
      type: integer
    name:
      type: string
    variety:
      type: string

Note:

  1. I still have version 1 Apple objects in my database, which will be served over the same API.
  2. I want to accurately mark fields as required in the v2 model, because this is important spec information.
  3. It's not appropriate to version my entire API, because there are many types of model besides Apple and doing so would result in a massive number of versions.

Does OpenAPI version 3 have a way of versioning individual models' schemas? I can't see anything obvious in the spec. I don't want to just extend objects and make all the fields optional, as that would be incorrect.

My only option seems to be to define an Apple1 and an Apple2, but that seems ungainly.

0 Answers
Related