OAI / OAI/sig-lifecycle

Allow versioning at path:method level

Open
#13 8 comments 25 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
3
Forks
4
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no repository files, tests, or entry points; start by locating the path/method versioning model and its schema or validation tests. Done means supporting the proposed versions array at path:method level without removing existing functionality, including both single- and multiple-version examples.

Written by the indexing model from the issue text.

Assessment

Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.