@nestjs/swagger

@nestjs/swagger is the official NestJS module for generating OpenAPI 3 specifications directly from your existing controllers, DTOs, and decorators, rather than requiring a hand-maintained YAML/JSON spec. It scans your application’s routes and TypeScript types at bootstrap and produces both a machine-readable OpenAPI document and an interactive Swagger UI page, using decorators like @ApiProperty() and @ApiOperation() to enrich the generated schema with descriptions, examples, and validation constraints.

A companion CLI plugin can additionally read your TypeScript AST at build time to infer property types and add many @ApiProperty() annotations automatically, cutting down the amount of decorator boilerplate needed to keep documentation in sync with code.

What You Get

• DocumentBuilder - a fluent builder for describing API-level metadata (title, description, version, servers, security schemes)
• SwaggerModule.setup() - serves an interactive Swagger UI page and the raw OpenAPI JSON/YAML from your running Nest app
• @ApiProperty(), @ApiOperation(), @ApiResponse() and related decorators for enriching generated schemas with descriptions, examples, and types
• A CLI/webpack plugin that statically analyzes your TypeScript to auto-generate @ApiProperty() decorators, reducing manual annotation
• Support for OpenAPI security schemes (bearer, API key, OAuth2, cookie) mapped onto Nest guards

Common Use Cases

• Publishing always-in-sync interactive API documentation for a NestJS REST API without hand-writing an OpenAPI spec
• Generating a typed OpenAPI contract that frontend teams or codegen tools (openapi-generator, orval) consume to produce API clients
• Documenting authentication requirements (JWT bearer, API key) alongside endpoint definitions for API consumers
• Enforcing consistent request/response DTO shapes across a large NestJS codebase via shared @ApiProperty() decorators

Under The Hood

Architecture The library (~11,500 lines) centers on swagger-scanner.ts, swagger-explorer.ts, and swagger-transformer.ts in lib/, which walk a Nest application’s compiled module graph at bootstrap to discover controllers, routes, and DTO metadata, then transform that into an OpenAPI 3 document object; swagger-module.ts exposes the public SwaggerModule.createDocument()/.setup() entry points, and swagger-ui/ bundles and serves the interactive documentation page. A separate plugin/ directory implements a TypeScript AST-analysis plugin that runs at build time (via nest-cli.json or webpack) rather than at request time. Tech Stack Built in TypeScript against @nestjs/common/@nestjs/core as peer dependencies, bundling swagger-ui-dist for the documentation UI and using the OpenAPI 3 specification as its output format; the CLI plugin uses the TypeScript compiler API directly for static type inference. Code Quality test/ mirrors the lib/ structure module-for-module (separate decorators, explorer, plugin, swagger-ui, type-helpers, and utils test directories) plus a distinct e2e/ suite run via its own Vitest config — a clear separation between fast unit tests and slower end-to-end scans of real Nest applications. API Design The decorator surface (@ApiProperty, @ApiOperation, @ApiResponse, etc.) follows NestJS’s existing decorator conventions closely, and DocumentBuilder’s fluent chaining mirrors patterns already familiar from other builder-style NestJS APIs, keeping the learning curve low for anyone already using the framework — the main complexity is knowing which OpenAPI concepts (schemas, security schemes) map to which decorator.