Добавление Swagger в проект NestJS

disel

Swagger — это инструмент для документирования API, который позволяет автоматически генерировать документацию на основе вашего кода. В NestJS интеграция Swagger осуществляется с помощью официального пакета @nestjs/swagger.

Шаги для добавления Swagger в проект

  1. Установите зависимости: Установите необходимые пакеты для работы со Swagger:bashnpm install --save @nestjs/swagger swagger-ui-express
  2. Настройте Swagger в main.ts: В файле main.ts добавьте конфигурацию Swagger:typescriptimport { NestFactory } from '@nestjs/core'; import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'; import { AppModule } from './app.module'; async function bootstrap() { const app = await NestFactory.create(AppModule); // Настройка Swagger const config = new DocumentBuilder() .setTitle('Documents API') .setDescription('API для работы с документами') .setVersion('1.0') .addTag('documents') .build(); const document = SwaggerModule.createDocument(app, config); SwaggerModule.setup('api', app, document); await app.listen(3000); } bootstrap();
    • setTitle: Устанавливает заголовок документации.
    • setDescription: Добавляет описание API.
    • setVersion: Указывает версию API.
    • addTag: Добавляет теги для группировки эндпоинтов.
    После этого Swagger-документация будет доступна по адресу: http://localhost:3000/api.
  3. Добавьте декораторы Swagger в контроллер: Используйте декораторы из @nestjs/swagger, чтобы описать эндпоинты и их параметры.Пример для documents.controller.ts:typescriptimport { Controller, Get, Post, Body, Param } from '@nestjs/common'; import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger'; import { DocumentsService } from './documents.service'; import { CreateDocumentDto } from './dto/create-document.dto'; @ApiTags('documents') // Группировка эндпоинтов под тегом "documents" @Controller('documents') export class DocumentsController { constructor(private readonly documentsService: DocumentsService) {} @ApiOperation({ summary: 'Получить все документы' }) @ApiResponse({ status: 200, description: 'Список документов успешно получен.' }) @Get() async findAll() { return this.documentsService.findAll(); } @ApiOperation({ summary: 'Получить документ по ID' }) @ApiResponse({ status: 200, description: 'Документ успешно найден.' }) @ApiResponse({ status: 404, description: 'Документ не найден.' }) @Get(':id') async findOne(@Param('id') id: number) { return this.documentsService.findOne(id); } @ApiOperation({ summary: 'Создать новый документ' }) @ApiResponse({ status: 201, description: 'Документ успешно создан.' }) @Post() async create(@Body() createDocumentDto: CreateDocumentDto) { return this.documentsService.create(createDocumentDto); } }
  4. Добавьте описания для DTO: Чтобы Swagger мог корректно отображать параметры запросов, добавьте декораторы в DTO.Пример для create-document.dto.ts:typescriptimport { ApiProperty } from '@nestjs/swagger'; import { IsDate, IsNotEmpty, IsString } from 'class-validator'; export class CreateDocumentDto { @ApiProperty({ example: 'DOC-123', description: 'Номер документа' }) @IsNotEmpty() @IsString() documentNumber: string; @ApiProperty({ example: '2025-02-21T00:00:00.000Z', description: 'Дата документа' }) @IsNotEmpty() @IsDate() documentDate: Date; @ApiProperty({ example: 'Title of the document', description: 'Заголовок документа' }) @IsNotEmpty() @IsString() title: string; @ApiProperty({ example: '/path/to/document.pdf', description: 'Путь к файлу документа' }) @IsNotEmpty() @IsString() filepath: string; @ApiProperty({ example: 1, description: 'ID папки', required: false }) folderId?: number; @ApiProperty({ example: 2, description: 'ID типа документа', required: false }) documentTypeId?: number; }
    • @ApiProperty: Описывает свойства DTO для отображения в Swagger UI.

Проверка работы Swagger

  1. Запустите приложение:bashnpm run start
  2. Откройте браузер и перейдите по адресу:javascripthttp://localhost:3000/api Вы увидите автоматически сгенерированную документацию для вашего API.

Пример результата

В Swagger UI вы увидите:

  • Эндпоинты GET /documents, GET /documents/:id, POST /documents.
  • Описание каждого эндпоинта, включая параметры и примеры запросов/ответов.
  • DTO с примерами данных.

Теперь ваш проект поддерживает Swagger-документацию, что упрощает тестирование и использование API! 😊

Похожие записи/страницы: