OpenAPI 3.x: Scope of API version in servers definition too course grained?

[marwey]

Hi, I was building a few OpenAPI 3.0 yaml files each describing a couple of paths. All path definitions are at version 1.

My server object is defined similiar to that pattern:

servers:
 - url: https://development.gigantic-server.com/v1
  description: Development server
 - url: https://production.gigantic-server.com/v1
   description: Production server 

What if I decide to change the path definition and/or the implementation of a path in a way that makes it incompatible to version 1? I would need to define a version 2 path. But certainly only for that specific path - all others should stay at version 1.

However, my server definition from above would be useless since its scope is applied to all path.

I can think of some workarounds - like e.g. putting the version number as part of the path definition or defining another yaml spec that only includes the version 2 path - but they are not really elegant and will cause other problems.

What is best practice for this - I guess quite common - scenario?
What was the intention of the spec authors to provide the above servers pattern?

Thanks!

[webron]

We don't really recommend using the servers to describe different environments (such as prod, dev, staging and so on), especially for public facing APIs. You're pretty much exposing your environments to all your users.

As for your specific scenario, you can override the servers definition at the path level and the operation level, as needed.

[earth2marsh]

I'll add that often the spec can be expected to change across different lifecycle envs—that's how new features roll out, for example, and might even have a different version. In that case the spec itself will be different, and I would treat it as a different artifact rather than try to force different versions together in the same spec.

[stevendearborn]

See issue number #1397

[stevendearborn]

Looking at this while in the Swagger Editor and UI, the person reading and trying out the API would need to know the version; the version of the API needs to be disclosed to them somehow, either to bring up the correct artifact or to select the version from the server alternatives or variables.

[stevendearborn]

Similar to the 'operationId' property, if the Info object had an 'apiId' property whose value was unique to a given API then a comparison between OpenAPI JSON documents could determine the various versions for a given apiId. How about X-apiId for now?

Alternatively, the Info object could hold 'previous versions' property whose value is an array of JSON references. Using references then the files could be anywhere reachable and hosted on a network. Maybe X-versions for now?

[ioggstream]

, the Info object could hold 'previous versions' property whose value is an array of JSON references.

reasonable, or something like #1397 (comment)