Typableitung

Drei automatische Mechanismen: Interfaces werden zu Inline-Schema, class-validator wird zu JSON Schema, @HttpCode() ergibt den richtigen Status.

Interface-typisierte DTOs

Wenn ein Response- oder Body-Typ ein TypeScript-interface ist (keine Klasse), kann Swagger es nicht als type:-Wert nutzen, da Interfaces zur Laufzeit gelöscht werden. nestjs-docfy erkennt das automatisch und erzeugt ein Inline-schema:-Objekt, ohne Änderungen an deinem Code.

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

Erzeugte Ausgabe:

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

Unterstützt: Primitives, nullable Unions (T | null), Arrays, verschachtelte Interfaces und optionale Eigenschaften (aus required ausgeschlossen).

class-validator-Ableitung

Wenn eine DTO-Klasse class-validator-Decorators nutzt und noch nicht @ApiProperty auf ihren Eigenschaften hat, leitet nestjs-docfy ein vollständiges JSON Schema aus den Validierungs-Decorators ab, ganz ohne manuelle Annotation.

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;
}

Erzeugte Ausgabe:

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

Unterstützte Decorators

Decorator
@IsString
@IsEmail
@IsUrl
@IsUUID
@IsDateString
@IsNumber
@IsInt
@IsBoolean
@IsArray
@Min
@Max
@MinLength
@MaxLength
@IsOptional
Vorhandene Annotationen bleiben erhalten

Hat eine Eigenschaft der Klasse bereits @ApiProperty, wird die Ableitung übersprungen und stattdessen type: ClassName verwendet; deine bestehenden Swagger-Annotationen werden nie überschrieben.

@HttpCode()-Unterstützung

NestJS' @HttpCode()-Decorator überschreibt den Standard-HTTP-Statuscode für einen Route-Handler. nestjs-docfy liest ihn automatisch aus und nutzt den korrekten Code in der generierten ApiResponse.

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

Erzeugte Ausgabe:

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

Ohne @HttpCode() gelten die Standardcodes: 201 für @Post, 200 für jedes andere HTTP-Verb.