# nestjs-swagger-dto

> Nestjs swagger dto decorators

Latest version **3.8.5** (published 2025-10-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install nestjs-swagger-dto
pnpm add nestjs-swagger-dto
yarn add nestjs-swagger-dto
bun add nestjs-swagger-dto
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.8.5 |
| Published | 2025-10-16 |
| First published | 2021-05-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18.0.0 |
| Dependencies | 0 |
| Unpacked size | 42.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 33 |
| Author | glebbash |
| Maintainers | glebbash |
| Keywords | nestjs, typescript, swagger, dto |

## Links

- npm: https://www.npmjs.com/package/nestjs-swagger-dto
- Repository: https://github.com/glebbash/nestjs-swagger-dto
- Homepage: https://github.com/glebbash/nestjs-swagger-dto#readme
- Issues: https://github.com/glebbash/nestjs-swagger-dto/issues
- npm.io page: https://npm.io/package/nestjs-swagger-dto

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 3.8.5 (latest) — 2025-10-16
- 3.8.4 — 2025-03-24
- 3.8.3 — 2024-10-15
- 3.8.2 — 2024-08-29
- 3.8.1 — 2024-07-15
- 3.8.0 — 2024-04-23
- 3.7.0 — 2024-02-15
- 3.6.1 — 2024-02-15
- 3.6.0 — 2024-02-06
- 3.5.0 — 2023-02-15
- 3.4.0 — 2023-02-14
- 3.3.2 — 2022-09-19
- 3.3.1 — 2022-07-08
- 3.3.0 — 2022-05-26
- 3.2.1 — 2022-03-07
- … 17 more at https://npm.io/package/nestjs-swagger-dto/versions

## README

# nestjs-swagger-dto

[![Deploy](https://github.com/glebbash/nestjs-swagger-dto/workflows/build/badge.svg)](https://github.com/glebbash/nestjs-swagger-dto/actions)
[![Coverage Status](https://coveralls.io/repos/github/glebbash/nestjs-swagger-dto/badge.svg?branch=master)](https://coveralls.io/github/glebbash/nestjs-swagger-dto?branch=master)

## Nest.js Swagger DTO decorators

This library combines common `@nestjs/swagger`, `class-transformer` and `class-validator` decorators that are used together into one decorator for full Nest.js DTO lifecycle including OpenAPI schema descriptions.

<table>
<tr>
<th>DTO with nestjs-swagger-dto</th>
<th>DTO without nestjs-swagger-dto</th>
</tr>
<tr>
<td>

```ts
import { IsEnum, IsNested, IsString } from 'nestjs-swagger-dto';

class RoleDto {
  @IsString({
    optional: true,
    minLength: 3,
    maxLength: 256,
  })
  name?: string;

  @IsString({ optional: true, maxLength: 255 })
  description?: string;

  @IsEnum({ enum: { RoleStatus } })
  status!: RoleStatus;

  @IsNested({ type: PermissionDto, isArray: true })
  permissions!: PermissionDto[];
}
```

</td>
<td>

```ts
import { ApiProperty } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import { IsOptional, IsString, MaxLength, MinLength, ValidateNested } from 'class-validator';

export class RoleDto {
  @IsOptional()
  @IsString()
  @MinLength(3)
  @MaxLength(256)
  name?: string;

  @IsOptional()
  @IsString()
  @MaxLength(256)
  description?: string;

  @ApiProperty({ enum: RoleStatus, enumName: 'RoleStatus' })
  status!: RoleStatus;

  @ValidateNested({ each: true })
  @Type(() => PermissionDto)
  @ApiProperty({ type: [PermissionDto] })
  permissions!: PermissionDto[];
}
```

</td>
</tr>
</table>

## Installation

```sh
npm i nestjs-swagger-dto
```

## Contents

This library contains the following decorators

| Name       | Description                   |
| ---------- | ----------------------------- |
| IsBoolean  | boolean                       |
| IsConstant | constant                      |
| IsDate     | date / date-time              |
| IsEnum     | enum object / array of values |
| IsNested   | nested DTO                    |
| IsNumber   | numbers                       |
| IsObject   | typed plain js objects        |
| IsString   | strings                       |
| IsUnknown  | any json value                |

All of the decorators support the following parameters:

| Name        | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| description | adds description                                            |
| deprecated  | deprecates a field                                          |
| example     | adds example                                                |
| name        | sets the name for serialized property                       |
| optional    | makes property optional                                     |
| nullable    | makes property nullable                                     |
| isArray     | changes the type of property to array of items of this type |

Also decorators have additional parameters like: `min`, `max` for `IsNumber`.

### Headers validation

You can also validate request headers using `TypedHeaders` decorator.

```ts
export class TestHeaders {
  @IsString({
    // NOTE: header names will be lowercased automatically
    name: 'country-code',
    maxLength: 2,
    minLength: 2,
    example: 'US',
  })
  countryCode!: string;

  @IsString({
    name: 'timestamp',
    isDate: { format: 'date-time' },
  })
  timestamp!: string;
}

@Controller({ path: 'test', version: '1' })
export class TestController {
  @Get()
  async test(@TypedHeaders() headers: TestHeaders): Promise<string> {
    return headers.countryCode;
  }
}
```

## Other

Bootstrapped with: [create-ts-lib-gh](https://github.com/glebbash/create-ts-lib-gh)

This project is [MIT Licensed](LICENSE).

---
_Source: https://npm.io/package/nestjs-swagger-dto · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._