npm / @nestjs/swagger
@nestjs/swagger
What changed in @nestjs/swagger 12, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
9 breaking3 new APIs and options8 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@nestjs/swagger 1220 changes
Breaking changes 9
The CLI plugin now detects esmCompatible per source file from package.json type and the module setting when the option is unset; an explicit nest-cli.json value still wins.
lodash is no longer a runtime dependency; this affects projects that relied on it arriving transitively.
The peer dependency range is now ^12.0.0, so projects using @nestjs/swagger must align with Nest 12.
The peer dependency range is now ^12.0.0, so projects using @nestjs/swagger must align with Nest 12.
The package moves to 12.0.0 and its mapped-type helpers come from an ESM build aligned with the Nest 12 line.
The package is published as pure ESM with an exports map; import from the package root or @nestjs/swagger/plugin, because deep imports into build internals are no longer resolvable.
The package requires Node ^20.19.0 or >=22.12.0, where require(esm) is available without a flag.
For OpenAPI 3.1.0 and later, nullable schemas are normalized without the nullable keyword: typed schemas use a type union, enums gain null, and references and composites use anyOf.
For OpenAPI 3.0.x, nullable responses use the nullable keyword again, with the allOf wrapper for references, instead of oneOf with a null schema.
New APIs and options 3
Support is added for the HTTP QUERY method (RFC 10008).
With introspectComments enabled, JSDoc @param tags matched by route-parameter name set descriptions on generated @ApiQuery or @ApiParam decorators; existing explicit decorators are untouched.
This new document option converts Standard Schema values into OpenAPI schemas, can register extra components, and falls back to the DTO-derived schema when it returns undefined.
Fixes and other changes 8
Standard schema query parameters are merged with @ApiQuery.
The package is resolved through a bundler-visible dynamic import.
A standard-schema description is promoted to the parameter object.
The plugin treats single literal types as enums.
The generated file preserves $ characters when it is built.
TypeScript is declared as an optional peer dependency.
The plugin keeps the source package specifier for workspace imports.
Fixes hoisting of static imports in ESM.