Как поместитить параметры при создание записей swagger prisma nestjs

disel

Как поместить параметры при создании записей в Swagger с использованием Prisma и NestJS

Для интеграции Swagger с NestJS и Prisma, чтобы документировать параметры создания записей, необходимо использовать DTO (Data Transfer Object) и декораторы Swagger. DTO описывает структуру данных, которые ожидаются в запросе, а Swagger автоматически генерирует документацию на основе этих DTO.

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

1. Установите Swagger в проект

Если Swagger ещё не установлен, добавьте его в проект:

bash

1
npm install @nestjs/swagger swagger-ui-express

Настройте Swagger в main.ts:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
 
  const config = new DocumentBuilder()
    .setTitle('Weather Station API')
    .setDescription('API для управления метеостанциями')
    .setVersion('1.0')
    .build();
 
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);
 
  await app.listen(3000);
}
bootstrap();

Теперь Swagger будет доступен по адресу http://localhost:3000/api.

2. Создайте DTO для создания записи

Создайте DTO (например, weather-station-create.dto.ts) для описания структуры данных, которые ожидаются при создании записи:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
import { ApiProperty } from '@nestjs/swagger';
 
export class WeatherStationCreateDto {
  @ApiProperty({ example: 'Station 1', description: 'Название метеостанции' })
  name: string;
 
  @ApiProperty({ example: 'New York, USA', description: 'Расположение метеостанции' })
  location: string;
 
  @ApiProperty({ example: 25.5, description: 'Температура на метеостанции' })
  temperature: number;
}

Декоратор @ApiProperty используется для описания каждого свойства, чтобы Swagger мог автоматически сгенерировать документацию.

3. Используйте DTO в контроллере

В контроллере укажите DTO как тип данных для тела запроса:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { Body, Controller, Post } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';
import { WeatherStationCreateDto } from './dto/weather-station-create.dto';
 
@ApiTags('Weather Station')
@Controller('weather-station')
export class WeatherStationController {
  @Post()
  @ApiOperation({ summary: 'Создать новую метеостанцию' })
  create(@Body() data: WeatherStationCreateDto) {
    // Логика создания записи
    return { message: 'Weather station created', data };
  }
}
  • @ApiTags группирует маршруты в Swagger.
  • @ApiOperation добавляет описание для конкретного маршрута.

4. Генерация документации в Swagger

После выполнения вышеуказанных шагов Swagger автоматически сгенерирует документацию для вашего API. Пример документации для POST-запроса будет выглядеть так:

  • Endpoint: POST /weather-station
  • Body:json{ "name": "Station 1", "location": "New York, USA", "temperature": 25.5 }

5. Интеграция с Prisma

В сервисе используйте Prisma для сохранения данных в базу:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { WeatherStationCreateDto } from './dto/weather-station-create.dto';
 
@Injectable()
export class WeatherStationService {
  constructor(private readonly prisma: PrismaService) {}
 
  async create(data: WeatherStationCreateDto) {
    return this.prisma.weatherStation.create({
      data,
    });
  }
}

И вызовите этот метод в контроллере:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
import { Body, Controller, Post } from '@nestjs/common';
import { WeatherStationService } from './weather-station.service';
import { WeatherStationCreateDto } from './dto/weather-station-create.dto';
 
@Controller('weather-station')
export class WeatherStationController {
  constructor(private readonly weatherStationService: WeatherStationService) {}
 
  @Post()
  create(@Body() data: WeatherStationCreateDto) {
    return this.weatherStationService.create(data);
  }
}

Итог

Теперь ваш API задокументирован в Swagger, и вы можете видеть параметры, которые ожидаются при создании записи. Swagger автоматически сгенерирует документацию на основе DTO, а Prisma будет использовать эти данные для сохранения в базу данных. 🚀

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