-
Notifications
You must be signed in to change notification settings - Fork 228
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Supporting route version in @swagger route comment #67
Comments
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. |
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. |
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:
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). |
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. |
Closing for now as open api spec is now supported and workaround has been reported. |
Is it possible to specify the API Version in the route comment itself? meaning in the
@swagger
comment clause like the following file showsexamples/route2.js
: https://github.com/Surnet/swagger-jsdoc/blob/5cfd4ab866b0e75cb18793c63c46df63ea4dd752/example/routes2.jsThe text was updated successfully, but these errors were encountered: