# nestjs-swagger-decorator > Minimal swagger decorator for NestJS Latest version **1.4.0** (published 2024-10-05) · MIT license · 0 weekly downloads ## Install ```sh npm install nestjs-swagger-decorator pnpm add nestjs-swagger-decorator yarn add nestjs-swagger-decorator bun add nestjs-swagger-decorator ``` ## Health **Score 30/100 (F)** — status: maintenance-mode. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: stale; low maintenance score. ## Facts | | | |---|---| | Version | 1.4.0 | | Published | 2024-10-05 | | First published | 2022-11-18 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 5 | | Unpacked size | 53.7 KB | | Known vulnerabilities | 0 (+2 in 2 direct dependencies) | | Install scripts | no | | Author | happbob | | Maintainers | limms2000 | ## Links - npm: https://www.npmjs.com/package/nestjs-swagger-decorator - npm.io page: https://npm.io/package/nestjs-swagger-decorator ## Dependencies (5) - [@nestjs/core](https://npm.io/package/@nestjs/core.md) ^9.4.3 - [@nestjs/common](https://npm.io/package/@nestjs/common.md) ^9.4.3 - [@nestjs/swagger](https://npm.io/package/@nestjs/swagger.md) ^7.4.2 - [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.2.2 - [class-transformer](https://npm.io/package/class-transformer.md) ^0.5.1 ## Recent versions - 1.4.0 (latest) — 2024-10-05 - 1.3.0 — 2024-09-18 - 1.2.1 — 2024-09-17 - 1.2.0 — 2024-09-17 - 1.1.2 — 2022-11-23 - 1.1.1 — 2022-11-23 - 1.1.0 — 2022-11-23 - 1.0.16 — 2022-11-23 - 1.0.15 — 2022-11-21 - 1.0.14 — 2022-11-21 - 1.0.13 — 2022-11-21 - 1.0.12 — 2022-11-21 - 1.0.11 — 2022-11-21 - 1.0.10 — 2022-11-21 - 1.0.9 — 2022-11-21 - … 9 more at https://npm.io/package/nestjs-swagger-decorator/versions ## README # nestjs-swagger-decorator Minimal Swagger decorator for NestJS that simplifies complex response handling in your NestJS applications. ## How to install Install the package via npm or yarn: ```bash npm i nestjs-swagger-decorator # or yarn add nestjs-swagger-decorator ```
## Old Swagger Response Approach Handling multiple ApiResponse decorators can quickly clutter your code: ```ts @ApiResponse({ status: 200, description: 'Success', type: GetUserResponseDto }) @ApiResponse({ status: 401, description: 'Unauthorized' }) @ApiResponse({ status: 404, description: 'User not found' }) @ApiOperation({ summary: 'Get User by ID' }) async getUserById(@Param('id') id: string) { return this.userService.findById(id); } ``` This can be tedious and hard to manage as the number of responses grows.
## New Approach Using nestjs-swagger-decorator With nestjs-swagger-decorator, you can streamline the creation of your Swagger documentation: ### Example 1: Basic Usage ```ts /// user.swagger.ts import { BaseSwaggerDecorator } from 'nestjs-swagger-decorator'; import { GetUserResponseDto } from './dto/get-user-response.dto'; export function GetUserSwagger() { return BaseSwaggerDecorator( { summary: 'Get User by ID', description: 'Fetch user by their unique ID' }, [ { statusCode: 200, responseOptions: [ { model: GetUserResponseDto, exampleTitle: 'Success Response', exampleDescription: 'A valid user response', }, ], }, { statusCode: 404, responseOptions: [ { model: ErrorResponseDto, exampleTitle: 'User Not Found', exampleDescription: 'No user found with this ID', }, ], }, ], ); } ``` ```ts // user.controller.ts import { GetUserSwagger } from './user.swagger'; @Get(':id') @GetUserSwagger() async getUserById(@Param('id') id: string) { return this.userService.findById(id); } ``` Here, you define your Swagger documentation in a separate file and reuse it across your project, keeping your controller code clean.
### Example 2: Handling Multiple Responses If your API has several response scenarios (e.g., 200, 401, 404), you can handle them more easily using response options: ```ts // auth.swagger.ts import { BaseSwaggerDecorator } from 'nestjs-swagger-decorator'; import { LoginResponseDto } from './dto/login-response.dto'; import { ErrorResponseDto } from './dto/error-response.dto'; export function LoginSwagger() { return BaseSwaggerDecorator( { summary: 'User Login', description: 'Authenticate user credentials' }, [ { statusCode: 200, responseOptions: [ { model: LoginResponseDto, exampleTitle: 'Successful Login', exampleDescription: 'Valid credentials provided', }, ], }, { statusCode: 401, responseOptions: [ { model: ErrorResponseDto, exampleTitle: 'Unauthorized', exampleDescription: 'Invalid credentials', }, ], }, ], ); } ``` ```ts // auth.controller.ts import { LoginSwagger } from './auth.swagger'; @Post('login') @LoginSwagger() async login(@Body() loginDto: LoginDto) { return this.authService.login(loginDto); } ```
### Example 3: Using a Base Response DTO When you have a base response format that wraps your data, you can define and reuse it easily: ```ts // base-response.dto.ts export class BaseResponseDto { @ApiProperty({ example: 200 }) statusCode: number; @ApiProperty({ type: () => T }) data: T; @ApiProperty({ example: 'Request was successful' }) message: string; } ``` ```ts // project.swagger.ts import { BaseSwaggerDecorator } from 'nestjs-swagger-decorator'; import { BaseResponseDto } from './dto/base-response.dto'; import { ProjectDto } from './dto/project.dto'; export function GetProjectSwagger() { return BaseSwaggerDecorator({ summary: 'Get Project Details' }, [ { statusCode: 200, baseResponseDto: BaseResponseDto, responseOptions: [ { model: ProjectDto, exampleTitle: 'Project Found', exampleDescription: 'Project data returned successfully', }, ], }, ]); } ```
### Example 4: Custom Response Overwriting You can also customize responses by overwriting values in the response: ```ts // user.swagger.ts import { BaseSwaggerDecorator } from 'nestjs-swagger-decorator'; import { GetUserResponseDto } from './dto/get-user-response.dto'; export function GetUserSwagger() { return BaseSwaggerDecorator({ summary: 'Get User by ID' }, [ { statusCode: 200, responseOptions: [ { model: GetUserResponseDto, exampleTitle: 'User Found', exampleDescription: 'Valid user response', overwriteValue: { name: 'John Doe' }, }, ], }, { statusCode: 404, responseOptions: [ { model: ErrorResponseDto, exampleTitle: 'User Not Found', exampleDescription: 'No user found with this ID', overwriteValue: { message: 'No such user exists' }, }, ], }, ]); } ``` In this case, the response will return a user named “John Doe” in the example.
### Conclusion nestjs-swagger-decorator is designed to keep your code clean and concise while still providing rich Swagger documentation. Whether you’re dealing with multiple responses or need base response formats, this library has you covered. > Please visit my [github repository](https://github.com/happbob/nestjs-swagger-decorator), and star me! Special thanks to developer [@ImNM](https://github.com/ImNM) for reference. --- _Source: https://npm.io/package/nestjs-swagger-decorator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._