0
# @nestjs/swagger
1

2
**@nestjs/swagger** is the official OpenAPI (Swagger) integration library for NestJS applications. It provides comprehensive decorators, utilities, and configuration tools to automatically generate OpenAPI 3.0 specifications from your NestJS code, complete with interactive Swagger UI documentation.
3

4
## Package Information
5

6
| Field | Value |
7
|-------|--------|
8
| **Package** | @nestjs/swagger |
9
| **Version** | 11.2.0 |
10
| **License** | MIT |
11
| **Dependencies** | @nestjs/common, @nestjs/core, reflect-metadata |
12
| **Platform** | Node.js |
13
| **TypeScript** | Full TypeScript support with comprehensive type definitions |
14
15
## Installation
16

17
```bash
18
npm install @nestjs/swagger
19
```
20

21
## Core Imports
22

23
### ES Modules (ESM)
24
```typescript { .api }
25
import { 
26
  DocumentBuilder, 
27
  SwaggerModule, 
28
  ApiProperty, 
29
  ApiOperation,
30
  ApiResponse 
31
} from '@nestjs/swagger';
32
```
33

34
### CommonJS
35
```typescript { .api }
36
const { 
37
  DocumentBuilder, 
38
  SwaggerModule, 
39
  ApiProperty, 
40
  ApiOperation,
41
  ApiResponse 
42
} = require('@nestjs/swagger');
43
```
44

45
## Basic Usage
46

47
### Quick Setup
48
```typescript
49
import { NestFactory } from '@nestjs/core';
50
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
51
import { AppModule } from './app.module';
52

53
async function bootstrap() {
54
  const app = await NestFactory.create(AppModule);
55

56
  // Create OpenAPI document configuration
57
  const config = new DocumentBuilder()
58
    .setTitle('My API')
59
    .setDescription('API description')
60
    .setVersion('1.0')
61
    .addBearerAuth()
62
    .build();
63

64
  // Generate OpenAPI document
65
  const document = SwaggerModule.createDocument(app, config);
66
  
67
  // Setup Swagger UI
68
  SwaggerModule.setup('api', app, document);
69

70
  await app.listen(3000);
71
}
72
bootstrap();
73
```
74

75
### Annotating DTOs and Controllers
76
```typescript
77
import { ApiProperty, ApiOperation, ApiResponse } from '@nestjs/swagger';
78
import { Controller, Post, Body } from '@nestjs/common';
79

80
class CreateUserDto {
81
  @ApiProperty({ description: 'User name', example: 'John Doe' })
82
  name: string;
83

84
  @ApiProperty({ description: 'User email', example: 'john@example.com' })
85
  email: string;
86
}
87

88
@Controller('users')
89
export class UsersController {
90
  @Post()
91
  @ApiOperation({ summary: 'Create a new user' })
92
  @ApiResponse({ status: 201, description: 'User successfully created' })
93
  @ApiResponse({ status: 400, description: 'Bad request' })
94
  async create(@Body() createUserDto: CreateUserDto) {
95
    // Implementation
96
  }
97
}
98
```
99

100
## Architecture
101

102
### Core Components
103

104
**@nestjs/swagger** is built around six major modules that work together to provide comprehensive OpenAPI integration:
105

106
1. **Decorators** - Annotation system for marking up classes, methods, and properties with OpenAPI metadata
107
2. **DocumentBuilder** - Configuration builder for creating OpenAPI document specifications
108
3. **SwaggerModule** - Integration layer that connects NestJS applications with Swagger UI
109
4. **Type Helpers** - Utility functions for creating derived types (Partial, Pick, Omit, Intersection)
110
5. **Interfaces** - Complete TypeScript definitions for OpenAPI 3.0 specification objects
111
6. **Utils** - Helper functions for schema references and path generation
112

113
### Metadata Flow
114

115
```
116
NestJS Application
117
       ↓
118
   Decorators (Add OpenAPI metadata to classes/methods)
119
       ↓
120
   DocumentBuilder (Configure document structure)
121
       ↓
122
   SwaggerModule (Generate OpenAPI spec + Setup UI)
123
       ↓
124
   Swagger UI (Interactive documentation)
125
```
126

127
### Key Concepts
128

129
- **Decorators**: TypeScript decorators that attach OpenAPI metadata to classes, methods, and properties
130
- **Schema Generation**: Automatic conversion of TypeScript types to JSON Schema definitions
131
- **Document Configuration**: Builder pattern for creating comprehensive OpenAPI documents
132
- **UI Integration**: Seamless setup of interactive Swagger UI with customization options
133
- **Type Safety**: Full TypeScript support with compile-time validation
134

135
## Capabilities
136

137
### API Annotation System
138
Comprehensive decorator system for annotating every aspect of your API:
139

140
```typescript { .api }
141
import { 
142
  ApiProperty, 
143
  ApiOperation, 
144
  ApiResponse, 
145
  ApiParam, 
146
  ApiQuery,
147
  ApiHeader,
148
  ApiBody
149
} from '@nestjs/swagger';
150
```
151
**[→ Complete decorators reference](./decorators.md)**
152

153
### Document Configuration
154
Powerful builder for creating OpenAPI document specifications:
155

156
```typescript { .api }
157
import { DocumentBuilder } from '@nestjs/swagger';
158

159
const config = new DocumentBuilder()
160
  .setTitle('API')
161
  .setDescription('API description')
162
  .setVersion('1.0')
163
  .addServer('https://api.example.com')
164
  .addBearerAuth()
165
  .addTag('users', 'User management operations')
166
  .build();
167
```
168
**[→ DocumentBuilder API reference](./document-builder.md)**
169

170
### NestJS Integration
171
Seamless integration with NestJS applications:
172

173
```typescript { .api }
174
import { SwaggerModule } from '@nestjs/swagger';
175

176
// Generate OpenAPI document
177
const document = SwaggerModule.createDocument(app, config);
178

179
// Setup Swagger UI with customization
180
SwaggerModule.setup('api', app, document, {
181
  swaggerOptions: {
182
    persistAuthorization: true,
183
  },
184
});
185
```
186
**[→ SwaggerModule API reference](./swagger-module.md)**
187

188
### Type Utilities
189
Advanced type manipulation functions for creating derived DTOs:
190

191
```typescript { .api }
192
import { 
193
  PartialType, 
194
  PickType, 
195
  OmitType, 
196
  IntersectionType 
197
} from '@nestjs/swagger';
198

199
// Create partial type
200
class UpdateUserDto extends PartialType(CreateUserDto) {}
201

202
// Pick specific properties  
203
class UserSummaryDto extends PickType(User, ['id', 'name'] as const) {}
204

205
// Combine multiple types
206
class ExtendedUserDto extends IntersectionType(CreateUserDto, BaseDto) {}
207
```
208
**[→ Type helpers reference](./type-helpers.md)**
209

210
### Schema References and Utilities
211
Utilities for creating schema references and manipulating OpenAPI schemas:
212

213
```typescript { .api }
214
import { getSchemaPath, refs } from '@nestjs/swagger';
215

216
// Get schema reference path for a model class or string
217
function getSchemaPath(model: string | Function): string;
218

219
// Create multiple schema references from model classes
220
function refs(...models: Function[]): ReferenceObject[];
221

222
// Usage examples
223
const userSchemaRef = getSchemaPath(User);           // "#/components/schemas/User"
224
const productSchemaRef = getSchemaPath('Product');   // "#/components/schemas/Product"
225

226
// Create multiple schema references
227
const schemaRefs = refs(User, Product, Order);
228
// Returns: [
229
//   { $ref: "#/components/schemas/User" },
230
//   { $ref: "#/components/schemas/Product" }, 
231
//   { $ref: "#/components/schemas/Order" }
232
// ]
233
```
234

235
**Note**: These utilities are especially useful when creating complex response schemas or defining relationships between models in your OpenAPI documentation.
236

237
### OpenAPI Interfaces
238
Complete TypeScript definitions for OpenAPI 3.0 specification:
239

240
```typescript { .api }
241
import { 
242
  OpenAPIObject, 
243
  SchemaObject, 
244
  OperationObject,
245
  ResponseObject,
246
  ParameterObject 
247
} from '@nestjs/swagger';
248
```
249
**[→ Interfaces reference](./interfaces.md)**
250

251
### Security Integration
252
Built-in support for all OpenAPI security schemes:
253

254
```typescript { .api }
255
import { 
256
  ApiSecurity, 
257
  ApiBearerAuth, 
258
  ApiBasicAuth, 
259
  ApiOAuth2,
260
  ApiCookieAuth 
261
} from '@nestjs/swagger';
262

263
@ApiBearerAuth() // JWT Bearer token
264
@ApiBasicAuth()  // HTTP Basic auth
265
@ApiOAuth2(['read', 'write']) // OAuth2 with scopes
266
class SecureController {}
267
```
268

269
### Advanced Features
270
- **Plugin System**: Automatic metadata generation via TypeScript compiler plugin
271
- **Custom Extensions**: Support for OpenAPI extensions (x-* properties)
272
- **Validation Integration**: Works seamlessly with class-validator decorators
273
- **Multi-format Support**: JSON and YAML document generation
274
- **UI Customization**: Extensive Swagger UI theming and behavior options
275

276
---
277

278
This package provides everything needed to create professional, interactive API documentation for NestJS applications with minimal effort while maintaining full type safety and extensive customization options.