How do you document DTO properties for Swagger and handle optional vs required fields in NestJS?

Q: How do you document DTO properties for Swagger and handle optional vs required fields in NestJS?

export class CreateUserDto { @ApiProperty({ description: 'User email address', example: 'user@example.com', }) @IsEmail() email: string; @ApiProperty({ description: 'Password — minimum 8 characters', minLength: 8, example: 'Secur3P@ss', }) @MinLength(8) password: string; @ApiPropertyOptional({ description: 'User display name', example: 'Alice Smith', }) @IsOptional() @IsString() name?: string; @ApiProperty({ enum: UserRole, default: UserRole.USER }) @IsEnum(UserRole) role: UserRole = UserRole.USER; @ApiProperty({ type: [String], example: ['admin', 'user'] }) @IsArray() @IsString({ each: true }) tags: string[]; @ApiProperty({ type: AddressDto }) @ValidateNested() @Type(() => AddressDto) address: AddressDto; } @ApiProperty() — marks the field as required in the Swagger schema. @ApiPropertyOptional() — marks the field as optional; equivalent to @ApiProperty({ required: false }). Arrays require explicit type: [ElementType] — TypeScript metadata does not capture array element types. Enums require explicit enum: EnumType — TypeScript emits the union type, not the enum object. Nested DTOs require explicit type: NestedDto — the Swagger plugin can infer this but explicit is safer.

Difficulty: 5/10

Swagger decorators, DTO validation, optional vs required fields

Use @ApiProperty() for required fields and @ApiPropertyOptional() for optional fields. Both accept a configuration object for description, example, enum, type, and format. Arrays require explicit type: [ElementType]. Nested DTOs require type: NestedDto. NestJS auto-infers basic types from TypeScript but explicit decorators are required for arrays, enums, and nullable fields.

DTO Swagger documentation with @ApiProperty

@ApiProperty vs @ApiPropertyOptional:

1
@ApiProperty() — marks the field as required in the Swagger schema.
2
@ApiPropertyOptional() — marks the field as optional; equivalent to @ApiProperty({ required: false }).

How do you document DTO properties for Swagger and handle optional vs required fields in NestJS?

Difficulty: 5/10

Swagger decorators, DTO validation, optional vs required fields

Use @ApiProperty() for required fields and @ApiPropertyOptional() for optional fields. Both accept a configuration object for description, example, enum, type, and format. Arrays require explicit type: [ElementType]. Nested DTOs require type: NestedDto. NestJS auto-infers basic types from TypeScript but explicit decorators are required for arrays, enums, and nullable fields.

DTO Swagger documentation with @ApiProperty

@ApiProperty vs @ApiPropertyOptional:

1
@ApiProperty() — marks the field as required in the Swagger schema.
2
@ApiPropertyOptional() — marks the field as optional; equivalent to @ApiProperty({ required: false }).

How do you document DTO properties for Swagger and handle optional vs required fields in NestJS?

How do you document DTO properties for Swagger and handle optional vs required fields in NestJS?

Scenario Questions

Follow-up Questions