NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #3803 most downloaded on npm
Nest - modern, fast, powerful node.js web framework (@swagger)
Last release 11 days ago
23 Sep 2026
Ships fairly regularly
a new release about every 4 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
9 years old
258 releases · first in 2017
fix(plugin): treat single literal types as enums by @y-hsgw in #4097
Full Changelog: 12.0.1...12.0.2
One column per quarter.
Kamil Mysliwiec ( @kamilmysliwiec )
@nestjs/swagger is now a native ES module , requires Nest 12, and changes how nullable schemas are spelled in the generated document.
@nestjs/swagger is now a native ES module, requires Nest 12, and changes how nullable schemas are spelled in the generated document.
The package is published as pure ESM ("type": "module", compiled with NodeNext) behind a proper exports map. The legacy root index.ts / plugin.js / plugin.ts shims are gone, and deep imports into build internals are no longer resolvable — import from the package root (@nestjs/swagger) or from @nestjs/swagger/plugin.
You do not need to convert your app to ESM. Thanks to Node's require(esm) support, a CommonJS app can keep doing const { SwaggerModule } = require('@nestjs/swagger'). The CLI plugin entry (@nestjs/swagger/plugin) also keeps a require condition so nest-cli.json setups load it unchanged.
This is why the package now declares "engines": { "node": "^20.19.0 || >=22.12.0" } — those are the Node versions where require(esm) is available without a flag.
@nestjs/common and @nestjs/core peers are now ^12.0.0. @nestjs/mapped-types moves to 12.0.0 (itself ESM, with its major aligned to the Nest 12 line), so PartialType, PickType, OmitType and IntersectionType come from an ESM build too.
Schemas passed to Nest 12's route decorators (for example @Body({ schema: z.object({ ... }) })) can now be reflected into the OpenAPI document. Supply an adapter via the new standardSchemaConverter document option:
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import type { SwaggerDocumentOptions } from '@nestjs/swagger';
import { createSchema } from 'zod-openapi';
import type { ZodType } from 'zod';
// Standard Schema exposes the producing library under `~standard.vendor`,
// which is how you narrow the raw value to a library-specific type.
function isZodSchema(schema: unknown): schema is ZodType {
return (
!!schema &&
typeof schema === 'object' &&
(schema as { '~standard'?: { vendor?: string } })['~standard']?.vendor ===
'zod'
);
}
const options: SwaggerDocumentOptions = {
standardSchemaConverter: (schema, { schemaType }) => {
if (isZodSchema(schema)) {
const { schema: converted, components } = createSchema(schema, {
io: schemaType,
openapiVersion: '3.0.0'
});
return { schema: converted, components };
}
}
};
SwaggerModule.createDocument(app, config, options);SwaggerDocumentOptions, StandardSchemaConverter and StandardSchemaConversionResult are all exported from @nestjs/swagger; createSchema comes from [zod-openapi](https://www.npmjs.com/package/zod-openapi) (for Valibot, use toJsonSchema from @valibot/to-json-schema with target: 'openapi-3.0' and check for the 'valibot' vendor instead). Neither is a dependency of this package — install whichever converter matches the schema library you use.
The callback receives the raw schema value plus whether an input or output schema is wanted, so you can narrow to library-specific types without unsafe casts, and return extra components to register. Returning undefined falls back to the DTO-derived schema, so one converter can handle several libraries and ignore the rest. Standard Schema overrides apply to bodies, queries, params, unions and enums, and take priority over the DTO-derived schema.
Nullable schemas are now normalized once on the finished document, matching the version it declares:
nullable keyword (removed in JSON Schema 2020-12) is gone. Typed schemas become a type union (type: ['string', 'null']), enums gain a null value, and references and composite schemas become anyOf: [<schema>, { type: 'null' }]. The 3.0 type: 'object' + allOf wrapper around nullable references is unwrapped. Previously these documents carried nullable, which strict 3.1 consumers silently ignore — reading the property as non-nullable.nullable keyword (with the allOf wrapper for references). Since #3897 they emitted oneOf: [<schema>, { type: 'null' }], a type: 'null' that 3.0 does not define.The pass covers schema properties, parameters, headers, request bodies, responses, callbacks and webhooks, plus any nullable you wrote by hand. Free-form positions (example, examples, default, const, enum) and x- extensions are left alone. Snapshot tests asserting nullable: true in 3.1 documents, or oneOf in 3.0 responses, will need updating.
Closes #4063.
lodash is no longer a runtime dependency — internals use es-toolkit/compat. This shrinks the install footprint and only affects you if you relied on lodash arriving transitively.
esmCompatible is now auto-detected per file. The plugin resolves each source file's implied module format (via package.json type and the module setting) and emits ESM-compatible output for ESM projects. Setting esmCompatible explicitly in nest-cli.json still wins — the resolved value is only used when you left it unset. Fixes generated imports in ESM projects that previously got CJS-shaped output.@param tags now become descriptions. With introspectComments on, a @param tag is matched to the route parameter by name and sets the description on the generated @ApiQuery / @ApiParam. Existing explicit @ApiQuery / @ApiParam decorators are left untouched. Closes #2784.require export condition was added for the plugin entry so CJS-based CLI setups keep working. Fixes #3944.For most apps the upgrade is: bump @nestjs/swagger to ^12.0.0 alongside Nest 12, make sure you are on Node 20.19+ / 22.12+, and re-check any committed OpenAPI snapshot for the nullable spelling above.
Nothing published for this version
Nothing published for this version
Nothing published for this version
fix(plugin): preserve inferred responses for enum error statuses by @GiHoon1123 in #4014
Full Changelog: 11.4.6...11.4.7
## 11.4.6 (2026-07-17) #### Features * #3964 feat(plugin): infer ApiParam enum from @Param literal-union types (@y-hsgw) #### Bug fixes * #3947 fix(ty
feat(plugin): generate additionalProperties for Record/index-signature types by @y-hsgw in #3957
Full Changelog: 11.4.4...11.4.5
Alexander Scholz (@LucidityDesign)
Thibault Haffner (@tibohaffner)
Peter Grassberger (@PeterTheOne)
## 11.4.1 (2026-04-22) #### Bug fixes * #3871 fix(plugin): avoid duplicate keys when auto-generating @ApiOperation (@yogeshwaran-c) #### Committers: 1
## 11.4.0 (2026-04-22) #### Features * #3868 feat(plugin): auto-mark optional @Query parameters as required: false (@yogeshwaran-c) * #3725 feat(swagg
fix(plugin): remap import paths within rootDir to outDir by @alex-all3dp in https://github.com/nestjs/swagger/pull/3858
Full Changelog: https://github.com/nestjs/swagger/compare/11.3.1...11.3.2
Kamil Mysliwiec (@kamilmysliwiec)
Rajasekar Janakiraman (@rajasekar33)
fix(deps): update dependency lodash to v4.18.1 [security] by @renovate[bot] in https://github.com/nestjs/swagger/pull/3808
Full Changelog: https://github.com/nestjs/swagger/compare/11.2.6...11.2.7
feat: support adding custom fields on the servers[*] entry by @micalevisk in https://github.com/nestjs/swagger/pull/3715
servers[*] entry by @micalevisk in https://github.com/nestjs/swagger/pull/3715Full Changelog: https://github.com/nestjs/swagger/compare/11.2.5...11.2.6
Jacek Tomaszewski (@jtomaszewski)
chore(deps): update dependency @fastify/static to v9 by @renovate[bot] in https://github.com/nestjs/swagger/pull/3667
Full Changelog: https://github.com/nestjs/swagger/compare/11.2.3...11.2.4
Revert "fix(plugin): add async modifier when a reference is await import statement" by @kamilmysliwiec in https://github.com/nestjs/swagger/pull/3633
Full Changelog: https://github.com/nestjs/swagger/compare/11.2.2...11.2.3
## 11.2.2 (2025-11-16) #### Bug fixes * #3603 fix(plugin): add async modifier when a reference is await import statement (@seonggukchoi) #### Dependen
feat(@ApiExtension): When used on a controller it applies to all methods by @drewish in https://github.com/nestjs/swagger/pull/3485
Enum | null (and ar… by @AliRaZa1121 in https://github.com/nestjs/swagger/pull/3544Full Changelog: https://github.com/nestjs/swagger/compare/11.2.0...11.2.1
## 11.2.0 (2025-05-05) #### Enhancements * #3424 feat(document-builder): add support for setting extensions inside the info object (@daniseijo) * #324
## 11.1.6 (2025-04-30) #### Enhancements * #3423 feat(swagger-plugin): add skipDefaultValues option to omit unspecified default fields and correspondi
## 11.1.5 (2025-04-22) #### Bug fixes * #3413 fix: type import syntax for ApiResponse in esmCompatible (@CatsMiaow) #### Committers: 1 - Meow (@CatsMi
feat(schema): add duplicate DTO detection in schema exploration by @Newbie012 in https://github.com/nestjs/swagger/pull/3400
Full Changelog: https://github.com/nestjs/swagger/compare/11.1.3...11.1.4
## 11.1.3 (2025-04-14) #### Bug fixes * #3399 fix: import handling for ESM compatibility (@CatsMiaow) #### Dependencies * #3397 fix(deps): update depe
Kamil Mysliwiec (@kamilmysliwiec)
## 11.1.1 (2025-04-04) #### Bug fixes * #3369 fix: recursive schema reference handling #3368 (@bderevyaga) #### Dependencies * #3375 fix(deps): update
Kamil Mysliwiec (@kamilmysliwiec)
fix: skip printing warnings for fastify https://github.com/nestjs/swagger/commit/d817ca8d1cc78945e1e092215a264a9b5955af44 by @kamilmysliwiec
selfRequired: false not making an object-type property optional by @flovouin in https://github.com/nestjs/swagger/pull/3347Full Changelog: https://github.com/nestjs/swagger/compare/11.0.6...11.0.7
## 11.0.6 (2025-02-28) #### Bug fixes * #3324 feat: support native private class properties in model class visitor (@rklos)) #### Committers: 1 - Rado
fix: strip inline path regexps (fastify) https://github.com/nestjs/swagger/issues/3318
Full Changelog: https://github.com/nestjs/swagger/compare/11.0.4...11.0.5
fix(swagger-options): add persistAuthorization to SwaggerUiOptions by @do-not-do-that in https://github.com/nestjs/swagger/pull/3306
Full Changelog: https://github.com/nestjs/swagger/compare/11.0.3...11.0.4
## 11.0.3 (2025-01-23) #### Bug fixes * #3264 fix: incorrect IsUuid class-validator decorator (@degradingsky746) #### Committers: 1 - Fozail (@degradi
Revert "feat: make generated require() ESM compatible https://github.com/nestjs/swagger/pull/3253
## 11.0.1 (2025-01-17) #### Dependencies * #3249 fix(deps): update dependency @nestjs/mapped-types to v2.1.0 ([@renovate[bot]](https://github.com/apps
This version is only compatible with @nestjs/{core,common,platform-express,platform-fastify,...} >= v11
This version is only compatible with @nestjs/{core,common,platform-express,platform-fastify,...} >= v11
Nothing published for this version
Nothing published for this version
## Unreleased (2025-01-10) #### Bug fixes * #3232 fix: missing ApiProperty enum undefined handling (@nxht) * #3223 fix: swagger crashed while using an
## 8.1.0 (2024-12-04) #### Enhancements * #3198 feat: support description in @ApiSchema (@ccaspers) * #3185 feat(swagger): add documentsEnabled option
Kamil Mysliwiec (@kamilmysliwiec)
Kamil Mysliwiec (@kamilmysliwiec)
## 8.0.5 (2024-11-08) #### Dependencies * #3158 fix(deps): update dependency @nestjs/mapped-types to v2.0.6 ([@renovate[bot]](https://github.com/apps/
## 8.0.4 (2024-11-08) #### Bug fixes * #3155 fix(plugin): resolve compiler option paths relative to base (@Michsior14) #### Dependencies * #3156 fix(d
Kamil Mysliwiec (@kamilmysliwiec)
Kamil Mysliwiec (@kamilmysliwiec)
## 8.0.1 (2024-10-29) #### Enhancements * #3129 feat: Add schema support for more option keys (@alex-statsig) #### Committers: 1 - Alex Coleman (@alex
## 8.0.0 (2024-10-28) #### Breaking changes * #3017 feat(@nestjs/swagger): defaults api tag to controller name * #2877 fix(): Updated types for Specif
@ApiSchema decorator to allow specification of the schema type nameMerge pull request #3031 from danielsharvey/feature/example-support
examples field in @ApiHeader (c7721d6)Merge pull request #3071 from nestjs/renovate/npm-path-to-regexp-vulnerability
docs: add deprecation warning on useless SwaggerCustomOptions properties
Merge pull request #2863 from NovikovEvgeny/partial-type-helper-add-skip-null-option
Merge pull request #2825 from nestjs/renovate/fastify-static-7.x-lockfile
UUID from node's crypto package (bdc130a)Merge branch 'ZainUrRehmanKhan-support_of_ApiParam_and_ApiQuery_for_controller'
Merge pull request #2697 from nestjs/renovate/swagger-ui-dist-5.x
Merge pull request #2684 from drewish/extensions
Your coding agent can read these notes before it upgrades. Set up the MCP server →