OpenAPI software version (#3104)
OpenAPI specs should have the version of the software/HTTP API they correspond
to embedded directly into the OpenAPI spec itself. This way if the relationship
between the spec and the repo its housed in is lost, such as in the two
examples given above, the version can be derived from the OpenAPI spec itself.
This proposal doesn't attempt to dictate what versioning system should be used
(e.g. semver, date based, git hash based), but rather propose where the version
should be stored in the OpenAPI spec.
Guidance
OpenAPI specs embedding the version of the software/HTTP API they correspond to
should use the info.x-oas-source meta data property name:
info:
x-oas-source: <version>
The value for the property should not only be the version of the software/HTTP
API that it refers to, but also the actual source that it belongs to, for
example the name of the software or the repository identifier where the source
is created. Very similar to the idea of "dependency" that carries information
on where and what version that is:
info:
x-oas-source: <source-package-or-repository>@<source-version-identifier>
The format here would be defined as an identifier for the source of the spec,
followed by a @ followed by a version identifier for the spec i.e.
source@version
The value should be changed whenever the spec is published elsewhere, either
via publishing to some sort of registry or simply copying the spec to another
repository that isn't the source repository.
Concrete Example
info:
x-oas-source: kong/platform-api@sha123
Notice we only use the short repository identifier for the left side of the @
not the entire URL.
OpenAPI has standard place to store meta data, in the info object
The object provides metadata about the API. The metadata MAY be used by the
clients if needed, and MAY be presented in editing or documentation
generation tools for convenience.
https://swagger.io/specification/#info-object
This info object MAY be extended with Specification Extensions
The extensions properties are implemented as patterned fields that are always
prefixed by x-.
https://swagger.io/specification/#specification-extensions