swagger
swagger copied to clipboard
nestjs
[discussion]: Multiple versions support at Swagger (Documents & UI)
Is there an existing issue that is already proposing this?
- [X] I have searched the existing issues
Is your feature request related to a problem? Please describe it
While developing an API, you usually want to have the ability to separate it into different versions. NestJS 8 can define versions at controllers or methods, and the latest @nestjs/swagger is bundling them into a single swagger document.
However, it's not always that easy for consumers to filter through all versions in a single place, and we could improve Swagger by using URLs with different specs per API version.
Describe the solution you'd like
An excellent example of such behavior has the Swashbuckle .Net implementation of swagger with the MultipleApiVersions feature - it generates multiple swagger documents per API version, collecting only controllers/methods with specific API version, and puts those swagger documents as specs to Swagger UI.
Example (top right corner):
Teachability, documentation, adoption, migration strategy
Right now, we are building a single Swagger document by providing a DocumentBuilder config to SwaggerModule.createDocument, and I think there are multiple possible ways to make it use better versions separations there:
Idea
We can add a version as a filter to SwaggerModule.createDocument, and change SwaggerModule.setup to accept & generate multiple swagger config documents with different content.
Multiple document usage will affect a swagger generation and require filtering by versions while collecting controllers, methods, DTOs, etc., for the Swagger document.
This change will be a major change to the document generation, as it will require the construction of multiple swagger documents and should work only if app.enableVersioning is enabled.
What is the motivation / use case for changing the behavior?
While building the API, versioning is vital to control the regression and integration. After the backend API reaches many API endpoints and gets a new version, filtering by versions for API consumers is pretty painful.
Having the ability to review & check API separated by a simple switch of different versions would increase overall satisfaction & productivity.
Let us know If it's not only us who have such an issue, and we'll try to contribute to this feature.
Any progress on this issue? I really would like to be able to work with multiple swagger versions
I just ran into the same issue. One of the main reasons I use swagger (with dotnet) is to have the ability to filter between multiple api versions, select and navigate between them.
@moewang0321， @volo-maslow，Excuse me, everyone, is there a solution for grouping interface documents as above? Thank you，This issue（issues/1840） is closed
Ran into the same issue. I was used to having versioning built in from different frameworks. Will this be resolved?
Using the tag Decorator is a workaround, but managing multiple API versions is appreciated, +1.
@ApiTags('resource', 'v1')
or
@ApiTags('/v1/resource')
+1 for this issue, I have a project for which I have enabled app.enableVersioning. Is there a way around it by enabling multiple versions of swagger?
+1 This would be really a nice feature to have. It's easier for consumers to understand and it would be also great to be able to give "newer" customers / consumers just the "newest" documentation of the API, without bothering them with the documentation of older versions
