Supporting route version in @swagger route comment

[lirantal]

Is it possible to specify the API Version in the route comment itself? meaning in the @swagger comment clause like the following file shows examples/route2.js: https://github.com/Surnet/swagger-jsdoc/blob/5cfd4ab866b0e75cb18793c63c46df63ea4dd752/example/routes2.js

[kalinchernev]

Hi @lirantal,
The API version can be set in the definition file input like this. I don't think it's much of a use to have versioning per-route.
Does this make sense?

[lirantal]

It definitely makes sense to have a per route API version because when you want to version your APIs then this happens on the route level, for example like this:

    app.get('/test', routesVersioning({
       "1.0.0": respondV1,
       "~2.2.1": respondV2
    }));

Having a single API version defined on the global file input like the example you referenced doesn't serve much purpose because that's an application-wide config and one Node.js Express app can serve multiple route versions.

[kalinchernev]

I quickly searched the current specification if such a property is to be set, but couldn't find an exact match out of the global one. Maybe the extension part would be a way to go, but it won't be a solution for any tool out there working with the specification.
As of this very moment, I don't know of the module to support any special per-route versioning out of the spec.
CC @chdanielmueller @drGrove any other ideas?

[lirantal]

My workaround is to specify versioning on the route itself, for example I can define multiple routes which have the exact same endpoint, except the version prefix:

  /**
   * @swagger
   * /v1/something/some
   */

  /**
   * @swagger
   * /v2/something/some
   */

but that's a rather bad work-around as it changes the actual endpoint in the documentation (although it could be supported from api versioning functionality).

[drGrove]

So I think this will be changing with OpenAPI v3. There's talk of supporting 'Accept' and 'Content-Type' headers. Of course this will not be a one-stop shop. But will at least have basic versioning support.

OAI/OpenAPI-Specification/issues/146

[kalinchernev]

Closing for now as open api spec is now supported and workaround has been reported.