Поясните цель декораторов @nestjs/swagger ApiProperty() и ApiOperation()

В NestJS, библиотека @nestjs/swagger предоставляет мощные инструменты для генерации документации API в формате OpenAPI (Swagger). Декораторы ApiProperty() и ApiOperation() играют ключевую роль в этом процессе, позволяя разработчикам описывать структуру их API и его поведение.

ApiProperty()

Декоратор ApiProperty() используется для описания свойств модели данных, которая будет использоваться в запросах и ответах API. Он помогает Swagger понять, какие поля доступны, их типы и любые дополнительные метаданные, такие как обязательность или описание.

Пример использования ApiProperty()

import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
  @ApiProperty({
    description: 'Имя пользователя',
    type: String,
    example: 'Иван',
  })
  name: string;

  @ApiProperty({
    description: 'Электронная почта пользователя',
    type: String,
    example: 'ivan@example.com',
  })
  email: string;

  @ApiProperty({
    description: 'Пароль пользователя',
    type: String,
    example: 'secret',
  })
  password: string;
}

В этом примере мы создали класс CreateUserDto, который описывает структуру данных для создания нового пользователя. Декоратор ApiProperty добавляет описание и пример для каждого поля, что упрощает понимание API пользователями.

ApiOperation()

Декоратор ApiOperation() используется для описания операции API (например, HTTP-метода и его цели). Он помогает уточнить информацию о конкретном эндпоинте, такую как его описание, возможные ответы и другие важные детали.

Пример использования ApiOperation()

import { Controller, Post, Body } from '@nestjs/common';
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
import { CreateUserDto } from './create-user.dto';

@ApiTags('пользователи')
@Controller('users')
export class UsersController {
  @Post()
  @ApiOperation({ summary: 'Создать нового пользователя' })
  @ApiResponse({ status: 201, description: 'Пользователь успешно создан.' })
  @ApiResponse({ status: 400, description: 'Ошибка валидации.' })
  async create(@Body() createUserDto: CreateUserDto) {
    // Логика создания пользователя
  }
}

В этом примере у нас есть контроллер UsersController, который обрабатывает запросы на создание пользователя. Декоратор ApiOperation описывает, что данный метод создает нового пользователя. Мы также используем ApiResponse, чтобы указать, какие статусы ответа могут быть возвращены в результате запроса.

Заключение

Декораторы ApiProperty() и ApiOperation() значительно упрощают создание и поддержку документации для RESTful API в приложениях на NestJS. Используя их должным образом, разработчики могут сделать свои API более понятными и легкими для интеграции. Это также помогает поддерживать высокий уровень качества кода и документации в проектах.