-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Open
Labels
metadatatags, info, license, contact, markdown usage, etc.tags, info, license, contact, markdown usage, etc.registriesRelated to any or all spec.openapis.org-hosted registriesRelated to any or all spec.openapis.org-hosted registriesversioningdescribing versions of APIs/endpoints/operationsdescribing versions of APIs/endpoints/operations
Description
This could be used to represent the version information of the described API. The current version
field is oftentimes misunderstood and misused to represent the API version information. Having a registry-based extension could help as a quick fix, and new versions (3.2 and/or 4) will hopefully fix the current gap at the standards level.
The risk is that this could then be used in newer versions as well. I don't know how much this should be see as an argument against the proposal.
Metadata
Metadata
Assignees
Labels
metadatatags, info, license, contact, markdown usage, etc.tags, info, license, contact, markdown usage, etc.registriesRelated to any or all spec.openapis.org-hosted registriesRelated to any or all spec.openapis.org-hosted registriesversioningdescribing versions of APIs/endpoints/operationsdescribing versions of APIs/endpoints/operations
Type
Projects
Milestone
Relationships
Development
Select code repository
Activity
handrews commentedon Nov 21, 2024
@dret We should see if we're going to put an
apiVersion
field in 3.2, and then if we put anx-
version in the registry for <=3.1, we can make it clear that there is a migration path.I just went to look for an issue for this to put into 3.2 and it looks like we don't actually have one? I really thought we did... I guess I'll just link to this issue for now (in discussion #4210).
dret commentedon Nov 21, 2024
lornajane commentedon Nov 28, 2024
Agreed not to add this as an extension, let's discuss if we can add it as a formal field in 3.2 to describe an API description that applies to only one version of an API, for APIs where that makes sense.
lornajane commentedon Nov 28, 2024
Related: OAI/sig-moonwalk#82
dret commentedon Nov 29, 2024
All good for me. Let's discuss what the best path looks like. My goal is to be able to represent version information about an API in OpenAPI. Ideally there would be a recommendation how to do it in existing versions as well.
[-]Add x-api-version to extension registry[/-][+]Support API-wide version information[/+]handrews commentedon Jan 25, 2025
I've updated the title of this issue because my eyes just kept sliding over the
x-
as "this isn't relevant to me..."I think we all know that there are many ways to version an API, and we're not going to figure out how to support all of them at once. Some are in-band, so there's really no need.
This is just to handle an out-of-band version field that applies to the entire API described by the OAD. I am sure someone will use it to duplicate version information already present in the Server Object URL, but we can't really prevent that from happening so I vote to just not worry about it- if people want to be redundant, they can deal with keeping things in sync. Or not.
The current
version
field is described as follows in 3.1.1:Other fields in the Info Object say they apply to "the API", which we never explicitly define but probably ought to define as "all paths and webhooks described when treating this document as the entry document."
I think this means that any
apiVersion
field MUST apply only when the document is used as an entry document.apiVersion
fields found in referenced documents MUST be ignored (this supports the use case where one API uses components from another API's entry document- not a use case I would recommend, but one that will no doubt happen).dret commentedon Jan 27, 2025
This all sounds good to me. There should be some model of how to decide what the "effective" API version is (if there are conflicting declarations), and using the entry document as an authoritative source sounds like a very reasonable model to me.
lornajane commentedon Feb 23, 2025
I am not in favour of this change (but always happy to be outvoted). API descriptions should be able to describe multiple API versions, and I think adding a field to say that the API is at a single version could encourage a practice that isn't terrible but definitely isn't "best practice". I wrote more about this https://redocly.com/blog/communicate-api-changes https://lornajane.net/posts/2023/when-to-version-bump-your-openapi-description
Many users are confused about the version field. Adding another version field doesn't seem like the best user experience change we could make here.
dret commentedon Feb 23, 2025
lornajane commentedon Feb 23, 2025
I believe that this is an API design and education issue as much as anything else. Sorry, I know it would be easier to add another field!!
15 remaining items