REST API Versioning with Swagger 2.0

Question

I needed my Node REST API's to be versioned. I am using swagger 2.0 for the validation middleware and documentation. Currently i have only a single swagger yml file that is used for all purposed.

I am using url prefixes (version number: /v1/... /v2/... etc) to support versioning in my Node Rest API. And i need to support multiple versions at any point of time.

1. Should i create a separate swagger yml file for each API version? If yes, how to load/manage multiple swagger yml files in the swagger-validation middleware
2. Does Swagger 2.0 format specification allow definition of versioned paths within the same file.

Answer 1

Swagger does not specify a versioning scheme simply because there is no single solution, and forcing one approach to use the spec would not make sense. Here are common techniques that I've seen:

1) Tie your authentication to a version. I think this is the coolest way to handle versioning but is also the most expensive to support and maintain. Based on, for example the api key being used to access your service, you can keep track of the version that they're expecting to access, and route it to the right server. In this case, you can simply have multiple services running, with different swagger definitions.

2) Use a path part to indicate the version. That means you have a /v2 or /v3 in your path, and based on that, some routing logic points you to the right server. Again, a separate swagger definition.

3) Based on some header, let the user choose what server to talk to. This is pretty unintuitive, but it can work. You should always have a default version (typically the latest)

That said, all of the above solutions mean multiple swagger files. You can use the $ref syntax to link and reuse portions of the spec.

I believe with swagger-tools, you can have multiple instances listening for requests. You just need a routing tier in front of them to handle the different versioning that you choose.