Inferenza dei tipi

Tre meccanismi automatici: le interface diventano schema inline, class-validator diventa JSON Schema, @HttpCode() diventa lo status corretto.

DTO tipizzati come interface

Quando un tipo di risposta o di body è una interface TypeScript (non una classe), Swagger non può usarla come valore di type: perché le interface vengono cancellate a runtime. nestjs-docfy lo rileva automaticamente e genera un oggetto schema: inline, senza alcuna modifica al tuo codice.

Sua interface
// Your existing interface (no need to convert to a class)
export interface RegisterResponseDto {
  success: boolean;
  message: string | null;
}

Output generato:

Generated
ApiResponse({
  status: 201,
  description: 'Created',
  schema: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      message: { type: 'string', nullable: true },
    },
    required: ['success'],
  },
}),

Supporta: primitivi, union nullable (T | null), array, interface annidate e proprietà opzionali (escluse da required).

Inferenza da class-validator

Quando una classe DTO usa decorator class-validator e non ha già @ApiProperty sulle sue proprietà, nestjs-docfy inferisce uno JSON Schema completo dai decorator di validazione, senza bisogno di annotazioni manuali.

create-user.dto.ts
// create-user.dto.ts
import { IsString, IsEmail, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;

  @IsOptional()
  @IsString()
  bio?: string;
}

Output generato:

ts
ApiBody({
  schema: {
    type: 'object',
    properties: {
      name:  { type: 'string', minLength: 2 },
      email: { type: 'string', format: 'email' },
      bio:   { type: 'string' },
    },
    required: ['name', 'email'],
  },
}),

Decorator supportati

Decorator
@IsString
@IsEmail
@IsUrl
@IsUUID
@IsDateString
@IsNumber
@IsInt
@IsBoolean
@IsArray
@Min
@Max
@MinLength
@MaxLength
@IsOptional
Preservare le annotazioni esistenti

Se una qualsiasi proprietà della classe ha già @ApiProperty, l'inferenza viene saltata e viene usato invece type: ClassName; le tue annotazioni Swagger esistenti non vengono mai sovrascritte.

Supporto a @HttpCode()

Il decorator @HttpCode() di NestJS sovrascrive il codice di stato HTTP predefinito per un route handler. nestjs-docfy lo legge automaticamente e usa il codice corretto nell'ApiResponse generato.

users.controller.ts
// users.controller.ts
@Post('logout')
@HttpCode(204)
logout(): void { ... }

Output generato:

ts
logout: [
  ApiOperation({ summary: 'Logout' }),
  ApiResponse({ status: 204, description: 'No Content' }),
],

Senza @HttpCode(), si applicano i codici predefiniti: 201 per @Post, 200 per ogni altro verbo HTTP.