Support API-wide version information

[dret]

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.

[handrews]

@dret We should see if we're going to put an api-version field in 3.2, and then if we put an x- 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]

On 2024-11-21 17:09, Henry Andrews wrote: We should see if we're going to put an |api-version| field in 3.2, and then if we put an |x-| version in the registry for <=3.1, we can make it clear that there is a migration path.

I agree that it would be good to clearly indicate the potential versioning issues. I very much hope to see API version being supported in version beyond 3.1

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 <#4210>).

I thought so, too. Maybe we had the discussion in some other place, but I cannot remember.

[lornajane]

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]

Related: OAI/sig-moonwalk#82

[dret]

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.

[handrews]

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:

REQUIRED. The version of the OpenAPI Document (which is distinct from the OpenAPI Specification version or the version of the API being described or the version of the OpenAPI Description).

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]

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.