# Nest Swagger

> Rules for writing @ApiProperty() decorators in NestJS DTOs. Use when adding or modifying @ApiProperty() in DTO files.

- Skill: `tiennguyen1203/nest-swagger` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tiennguyen1203/nest-swagger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tiennguyen1203/nest-swagger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tiennguyen1203 (https://skillmd.com/u/tiennguyen1203)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tiennguyen1203/nest-swagger

---


# NestJS Swagger @ApiProperty Skill

When adding or modifying `@ApiProperty()` decorators in NestJS DTOs, follow these rules to ensure the generated Swagger schema accurately reflects the TypeScript types.

## Rules

### 1. Optional fields (`IsOptional`)

If a property uses `@IsOptional()` or has `?` in its TypeScript type, apply `required: false`:

```ts
@ApiProperty({ required: false })
@IsOptional()
name?: string;
```

### 2. Nullable fields

If a property's type includes `null`, apply `nullable: true`:

```ts
@ApiProperty({ nullable: true })
deletedAt: Date | null;
```

Combine with optional when both apply:

```ts
@ApiProperty({ required: false, nullable: true })
@IsOptional()
reason?: string | null;
```

### 3. Enum fields

Always provide both `enum` and `enumName`:

```ts
@ApiProperty({ enum: StatusEnum, enumName: 'StatusEnum' })
status: StatusEnum;
```

### 4. Array fields

Use `type` + `isArray: true` instead of wrapping in `[]`:

```ts
@ApiProperty({ type: String, isArray: true })
tags: string[];

@ApiProperty({ type: ItemDto, isArray: true })
items: ItemDto[];
```

### 5. Combining rules

Apply all applicable rules together:

```ts
// optional array of enums
@ApiProperty({ enum: RoleEnum, enumName: 'RoleEnum', isArray: true, required: false })
@IsOptional()
roles?: RoleEnum[];

// nullable enum
@ApiProperty({ enum: StatusEnum, enumName: 'StatusEnum', nullable: true })
status: StatusEnum | null;
```