Fix/Feat: Support header-based versioning and filtering routes by version#3209
Fix/Feat: Support header-based versioning and filtering routes by version#3209aarongoin wants to merge 2 commits intonestjs:masterfrom
Conversation
…Options interface Add optional property `includeVersions` to the SwaggerDocumentOptions interface so users can filter the generated OpenAPI specification and resulting Swagger UI down to routes matching a specific version or subset of versions rather than including all versions as is the default behavior.
aarongoin
changed the title
|
|
||
| expect(api.paths['/api/dogs version: v0']).toBeUndefined(); | ||
|
|
||
| expect(api.paths['/api/dogs version: v1']['post']['operationId']).toBe('DogsController_createNewV1'); |
There was a problem hiding this comment.
Not sure if I'm following. How's this a valid path? (/api/dogs version: v1)
There was a problem hiding this comment.
Apologies for the delayed response.
You're correct that it's not a valid path, but there doesn't seem to be any other way of distinguishing between different versioned paths that route via headers when generating OpenAPI spec covering multiple versions simultaneously--something thats possible when versions are specified in the path. Unless perhaps you're suggesting to make it valid path via something like query params or hash route--though that doesn't seem ideal either.
I suppose the only other alternative is to force the user to specify a single API version to generate OpenAPI spec for (with option of including/excluding version-less routes). Do you prefer this alternative? Or do you have some other idea in mind for this?
2 participants
PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
npm run format)What is the current behavior?
Currently
@nestjs/waggerdoes not support header-based versioning that is documented as being supported here: https://docs.nestjs.com/techniques/versioning#header-versioning-typeIn addition end users lack any ability to filter the routes documented in the OpenAPI specification down to some subset of versions their app supports.
Issue Number: #2990
What is the new behavior?
Apps that use header-based versioning for endpoints (and I believe media-type based versioning as well though I haven't tested) are now properly supported. Endpoints of different versions using the same path no longer conflict with each other and are documented as separate endpoints in the resulting OpenAPI specification.
Additionally users can filter the endpoints documented down to a subset to better support use cases where there is a separate swagger document per API version.
Does this PR introduce a breaking change?
Other information