Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

[discussion]: Multiple versions support at Swagger (Documents & UI)

See original GitHub issue

Is there an existing issue that is already proposing this?

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.