Possibly related to #1572 . We have consumers of Counterfact that are supporting versioned APIs. Each version has its own Spec file but technically the same basePath. Actually OpenApi 3 does away with the basePath preferring the servers collection. So we can't rely on basePath to distinguish specs. Should we combine these two issues? Technically this one is slightly different in that we need to support multiple specs base on the version.
The problem is there isn't a single way to denote variant versions of a spec. Read this discussion here:
https://www.userosetta.com/blog/simplify-api-versioning-with-openapi
There is the info.version field in the spec header, but the stated purpose of that field isn't specifically to version the APIs so much as to version changes to the document. However, our consumers use that very field to denote the v1, v2, v3, etc versions. And the above article suggests using that header field is a perfectly valid way to distinguish versions.
Let's discuss the best path to implement this. I think it is reasonable to use the version field, but do we also infer the version from the servers collection as some documentation suggests?
In any case, it seems that if we load multiple specs that are variants, we need to build the types indedepently so that even if each spec has the same component name for a model we store it in a versioned path so that each model variant exists to be available as a type. So a v1 and v2 set of specs might have a component named PetModel live in two potential import paths:
/components/schemas/v1/PetModel
/components/schemas/v2/PetModel
Possibly related to #1572 . We have consumers of Counterfact that are supporting versioned APIs. Each version has its own Spec file but technically the same
basePath. Actually OpenApi 3 does away with thebasePathpreferring theserverscollection. So we can't rely onbasePathto distinguish specs. Should we combine these two issues? Technically this one is slightly different in that we need to support multiple specs base on the version.The problem is there isn't a single way to denote variant versions of a spec. Read this discussion here:
https://www.userosetta.com/blog/simplify-api-versioning-with-openapi
There is the
info.versionfield in the spec header, but the stated purpose of that field isn't specifically to version the APIs so much as to version changes to the document. However, our consumers use that very field to denote thev1,v2,v3, etc versions. And the above article suggests using that header field is a perfectly valid way to distinguish versions.Let's discuss the best path to implement this. I think it is reasonable to use the
versionfield, but do we also infer the version from theserverscollection as some documentation suggests?In any case, it seems that if we load multiple specs that are variants, we need to build the types indedepently so that even if each spec has the same component name for a model we store it in a versioned path so that each model variant exists to be available as a type. So a
v1andv2set of specs might have a component namedPetModellive in two potential import paths:/components/schemas/v1/PetModel/components/schemas/v2/PetModel