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.