Adding support for operation versioning

[adrael]

This new version property allows us to specify what version of the operation is behind the route.

BTW, thanks for all the work pals!

[adrael]

As requested, here is an example of a real-world need for this PR.
Feel free to add your own folks!

As of API versioning, one can choose from multiple solutions to implement and deploy versions.
For example:

• Path - /api/v1/pets
• Path - /pets-api/v1
• Content-type - Accept: application/vnd.pets.v1+json
• Custom header - api-version: 1

Obviously, the ones involving URL versioning are simple, you can simply look at the resource to know exactly where you're going.

My case is much more like the last one.
My team and I are using the amazing swagger-ui, and we use Header versioning. This offers the ability to version each resources independently.

It would be great to have the ability to choose which resource to use at a glance, like this:

I already created a PR (swagger-api/swagger-ui#3320) in the swagger-ui project to make it compatible with this potential API change.

[RobDolinMS]

@adrael Do you have concerns with moving this to after v3.0.0 ?

@darrelmiller may have an alternate approach.

[adrael]

@RobDolinMS As long as the idea of this PR gets checked and shipped, I don't see any concerns as of a 3.0.1 or even a 3.1.0 👍

[fehguy]

I don't think that moving it to post 3.0 is a guarantee that it'll be moved in. The point is the discussion will move to after the release.

[adrael]

@fehguy Yes I understand that, no problem!
Thanks guys!

Just curious, do you have any idea about a release date?

[joelharkes]

I think this should be out of scope of the api spec?

i would say: every version you generate is a new open api spec on which you can generate new client sdks.

if you want to support versioning, wouldn't it become far to complex?

Your spec now is: add a version number to operation to specify in which version it was added.
But the next feature will be to implement:

• Specify added properties in higher version of the operation, removed properties etc.

I think you should leave this out of the spec. The global version number defines what version the spec is based on, either version control (git) or seperate files per version can define what differs between versions (i.m.o).