Allow versioning at path:method level

To facilitate the option of media-type versioning, it would be helpful to version at the path:method level. Here is the gist of my proposal: move version from root level to path:method level and represent as an array of versions. In making the change as described, my hope is that none of the existing functionality is sacrificed.

Single version example

/pets/{id}:
  put:
    tags:
    - "pets"
    versions:
    - version: "default"
      summary: "..."
      description: "..."
      ... all other properties formerly defined in the path-item

Multiple version example

/pets/{id}:
  put:
    tags:
    - "pets"
    versions:
    - version: "1"
      summary: "..."
      description: "..."
      operationId: "updatePet_v1"
      consumes:
      - "application/json"
      - "application/vnd.vendor.v1+json"
      deprecated: true
      ... all other properties currently defined in the path-item
    - version: "2"
      summary: "..."
      description: "..."
      operationId: "updatePet_v2"
      consumes:
      - "application/vnd.vendor.v2+json"
      ... all other properties currently defined in the path-item

[jacobwod]

I understand that this issue/feature request is still unresolved.

Still, I’m wondering: what is the current best practice? Path versioning should be quite common when your API starts to grow, so perhaps I’m misunderstanding some part of the specification, while the solution is obvious to others?

[damonsutherland]

@gadton Thanks for pointing out another deficiency in the current 3.x spec with regards to media type versioning. To ensure I completely understand, let me restate.

Consider media-type versioning with the current 3.x spec:

openapi: 3.0.1
...
paths:
  /pets:
    post:
      tags:
      - pets
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet object that needs to be added to the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/vnd.vendor.v1+json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/vnd.vendor.v2+json:
            schema:
              $ref: '#/components/schemas/Pet_v2'
        required: true
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
            application/vnd.vendor.v1+json:
              schema:
                $ref: '#/components/schemas/Pet'
            application/vnd.vendor.v2+json:
              schema:
                $ref: '#/components/schemas/Pet_v2'
      ...

In the above scenario, it is unclear what request content-type/response content-type combinations are legal. The best we could do is add a 406 response code with documentation indicating valid combinations. However, a move to versioning at the path:method level, we get this:

openapi: 4.0.0
...
paths:
  /pets:
    post:
      tags:
      - pets
      versions:
      - version: 1
        summary: Create a new pet
        operationId: createPet
        requestBody:
          description: Pet object that needs to be added to the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
            application/vnd.vendor.v1+json:
              schema:
                $ref: '#/components/schemas/Pet'
          required: true
        responses:
          200:
            description: successful operation
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Pet'
              application/vnd.vendor.v1+json:
                schema:
                  $ref: '#/components/schemas/Pet'
      - version: 2
        summary: Create a new version 2 pet
        operationId: createPet_v2
        requestBody:
          description: Pet object that needs to be added to the store
          content:
            application/vnd.vendor.v2+json:
              schema:
                $ref: '#/components/schemas/Pet_v2'
          required: true
        responses:
          200:
            description: successful operation
            content:
              application/vnd.vendor.v2+json:
                schema:
                  $ref: '#/components/schemas/Pet_v2'
      ...

The intent is clear.