Решение проблемы генерации Swagger с помощью NestJS PartialType

NestJS — это популярная платформа Node.js, используемая для создания масштабируемых и удобных в обслуживании серверных приложений. Он предоставляет ряд мощных функций, включая встроенную поддержку создания документации API с помощью Swagger. Одной из наиболее часто используемых утилит в экосистеме NestJS является PartialType, которая упрощает процесс создания частичных DTO (объектов передачи данных). Однако могут быть случаи, когда PartialTypeне создает документацию Swagger должным образом. В этой статье мы рассмотрим эту проблему и обсудим несколько способов ее решения.

Понимание PartialTypeи документации Swagger.
Прежде чем углубиться в решение, давайте кратко разберемся, что такое PartialTypeи документация Swagger.

PartialType— это утилита NestJS, которая позволяет создавать частичные DTO путем наследования от существующего класса DTO и пометки всех свойств как необязательных. Это особенно полезно, если вы хотите обновить только подмножество свойств в запросе API.

Swagger — широко используемый инструмент для документирования RESTful API. Он обеспечивает структурированный способ описания конечных точек API, моделей запросов/ответов и других соответствующих деталей. NestJS легко интегрируется со Swagger, позволяя автоматически создавать документацию API на основе декораторов и метаданных.

Проблема: PartialTypeи создание Swagger:
В некоторых случаях использование только PartialTypeможет не привести к ожидаемому созданию документации Swagger. Это связано с тем, что модуль Swagger в NestJS использует декораторы TypeScript для вывода метаданных и создания документации. Поскольку PartialTypeсоздает новый класс динамически, он может не наследовать декораторы исходного класса DTO, что приводит к отсутствию документации в сгенерированном файле Swagger.

Решения.
Вот несколько способов решения проблемы:

  1. Декораторы Swagger вручную.
    Один из подходов — вручную применить декораторы Swagger к классу PartialType. Явно добавляя декораторы, такие как @ApiProperty(), @ApiBody()или @ApiQuery(), вы можете предоставить Swagger необходимые метаданные для создания точной документации.
import { PartialType } from '@nestjs/mapped-types';
import { ApiProperty } from '@nestjs/swagger';
import { CreateProductDto } from './create-product.dto';
export class UpdateProductDto extends PartialType(CreateProductDto) {
  @ApiProperty()
  name: string;
  @ApiProperty()
  price: number;
}
  1. Пользовательские декораторы.
    Другой подход — создание пользовательских декораторов, которые можно использовать с PartialTypeдля наследования метаданных из исходного класса DTO. Эти декораторы могут быть предназначены для копирования декораторов из исходного класса в частичный класс, гарантируя, что Swagger получит необходимую информацию.
import { PartialType } from '@nestjs/mapped-types';
import { CopyDecorators } from './copy-decorators.decorator';
import { CreateProductDto } from './create-product.dto';
@CopyDecorators(CreateProductDto)
export class UpdateProductDto extends PartialType(CreateProductDto) {
  name: string;
  price: number;
}
  1. Настройка Swagger вручную:
    Если описанные выше методы не работают, вы можете вручную настроить Swagger для включения недостающей документации. NestJS предоставляет SwaggerModule, где вы можете определить документацию вручную, указав недостающие свойства и их детали.
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
const options = new DocumentBuilder()
  .setTitle('Your API Title')
  .setDescription('Your API Description')
  .setVersion('1.0')
  .build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup('api', app, document);

Хотя PartialType— мощная утилита в NestJS, она не всегда может генерировать документацию Swagger должным образом. Используя ручные декораторы Swagger, пользовательские декораторы или ручную настройку, вы можете преодолеть это ограничение и обеспечить точную документацию API в своих файлах Swagger.

Помните, что создание подробной документации Swagger имеет решающее значение для повышения доступности и удобства использования ваших API, поэтому стоит потратить время на решение любых возникающих проблем.

Реализуя методы, описанные в этой статье, вы сможете решить проблему NestJS PartialType not generating Swaggerи обеспечить актуальность и информативность документации по API.