CODEWITHSUNDEEP
swaggerversioningopenapiopenapi-generator
fgysin
fgysin

Reputation: 11943

OAS3 specified Service Versioning

We are currently specifying a new REST service API using OpenAPI Service Specification v3 OAS3. Because of a bunch of different reasons we need/want to make the service API versioned from the start (this is mandated by factors not within our control).

The versioning scheme we would like to use is URL path versioning - i.e. something along the lines of .../v1/ourservice.

Does someone know how such a versioning scheme can be tracked in OAS3 specification?

So far I have only seen a global version attribute in OAS3 - but nothing that would allow us to easily specify multiple versions in one YAML file (or is this the wrong way to go about this in the first place?).

FYI, we are planning to use a top-down approach, i.e. define our service API as OAS3 YAML and then proceed to generate server and/client side code from that using Swagger generator.

Upvotes: 7

Views: 8629

Answers (1)

Jim Schubert
Jim Schubert

Reputation: 20367

version in the OpenAPI document refers to the version of the document not the version of the API.

From the spec:

version string REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

So, there are unfortunately three versions you'll need to be concerned with. Here's what those look like:

oepnapi: 3.0.2
  • The document version. I usually expose this as the git SHA1 hash for an auto-generated doc.
    Example (see version):
  title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
  • The API version.
    Some people consider path versioning controversial, but many of us (myself included) have to do this for a number of different reasons outside of our control. A common way to achieve this in all specification versions is to define the path version in baseUrl. For instance, your base URL could be /nested/v1 or simply /v1. This unfortunately would only cover the v1 approach.

OAS3 supports server variable templating for more complex API version configurations. This looks to be exactly what you're looking for. However, these variables aren't fully supported in all generators in OpenAPI Generator, yet. If you have specific generator(s) in mind, please open an issue for these as initial support appears to only exist in Ruby, PHP, python and JavaScript ES6 client generators.

Upvotes: 8

Related Questions