Add x-api-version to extension registry

[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.