Як документувати API NestJS за допомогою Swagger?
NestJS + Swagger (OpenAPI)
NestJS має першокласну підтримку для Swagger/OpenAPI документації через пакет @nestjs/swagger. Він автоматично генерує інтерактивну документацію API з ваших декораторів, DTO та контролерів.
Налаштування
bash
npm install @nestjs/swaggertypescript
// main.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('My API')
.setDescription('Документація REST API')
.setVersion('1.0')
.addBearerAuth() // додає заголовок Authorization: Bearer в UI
.addTag('users')
.addTag('auth')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api/docs', app, document); // → /api/docs
await app.listen(3000);
}
bootstrap();Документування DTO
typescript
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
export class CreateUserDto {
@ApiProperty({ example: 'Alice', description: 'Повне ім\'я', minLength: 2 })
@IsString()
name: string;
@ApiProperty({ example: 'alice@example.com' })
@IsEmail()
email: string;
@ApiPropertyOptional({ example: 25, minimum: 18 })
@IsOptional()
@IsInt()
age?: number;
@ApiProperty({ enum: ['user', 'admin'], default: 'user' })
@IsEnum(['user', 'admin'])
role: string;
}Документування контролерів
typescript
import {
ApiTags, ApiOperation, ApiResponse,
ApiBearerAuth, ApiParam, ApiQuery
} from '@nestjs/swagger';
@ApiTags('users') // групує кінцеві точки під "users"
@ApiBearerAuth() // вимагає JWT в Swagger UI
@Controller('users')
export class UsersController {
@Get()
@ApiOperation({ summary: 'Отримати всіх користувачів', description: 'Повертає пагінований список користувачів' })
@ApiQuery({ name: 'page', required: false, type: Number })
@ApiQuery({ name: 'limit', required: false, type: Number })
@ApiResponse({ status: 200, description: 'Повертає список користувачів', type: [UserResponseDto] })
findAll() { ... }
@Get(':id')
@ApiOperation({ summary: 'Отримати користувача за ID' })
@ApiParam({ name: 'id', type: Number })
@ApiResponse({ status: 200, type: UserResponseDto })
@ApiResponse({ status: 404, description: 'Користувача не знайдено' })
findOne(@Param('id') id: string) { ... }
@Post()
@ApiOperation({ summary: 'Створити нового користувача' })
@ApiResponse({ status: 201, type: UserResponseDto })
@ApiResponse({ status: 400, description: 'Помилка валідації' })
create(@Body() dto: CreateUserDto) { ... }
}DTO відповіді
typescript
import { Exclude, Expose } from 'class-transformer';
export class UserResponseDto {
@ApiProperty()
id: number;
@ApiProperty()
name: string;
@ApiProperty()
email: string;
@Exclude()
password: string; // виключено з серіалізованого виходу
}Серіалізація з ClassSerializerInterceptor
typescript
// Автоматично використовує DTO відповіді з @Exclude() / @Expose()
@Module({
providers: [
{
provide: APP_INTERCEPTOR,
useClass: ClassSerializerInterceptor,
},
],
})
// Контролер
@Get(':id')
@SerializeOptions({ type: UserResponseDto })
findOne(@Param('id', ParseIntPipe) id: number) {
return this.usersService.findOne(id); // пароль буде виключено
}Резюме
@nestjs/swagger автоматично генерує документацію OpenAPI з вашого коду TypeScript. Додайте @ApiProperty() до DTO та @ApiOperation(), @ApiResponse(), @ApiTags() до контролерів. Перейдіть до /api/docs під час розробки для інтерактивного Swagger UI, щоб протестувати ваші кінцеві точки API.
Коротка відповідь
Для співбесідиPremium
Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.