@nestjs/swagger

What is @nestjs/swagger?

The @nestjs/swagger package is used to create documentation for NestJS applications using the Swagger UI. It provides decorators and functions to define API endpoints, their expected request and response structures, and other metadata that can be used to generate interactive API documentation.

What are @nestjs/swagger's main functionalities?

API Documentation Setup

This code sets up Swagger documentation for a NestJS application. It uses the DocumentBuilder to configure the title, description, version, and other metadata for the API documentation. The SwaggerModule.createDocument function generates the Swagger specification, and SwaggerModule.setup mounts the documentation at the specified path.

const options = new DocumentBuilder()
  .setTitle('Cats example')
  .setDescription('The cats API description')
  .setVersion('1.0')
  .addTag('cats')
  .build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup('api', app, document);

Decorating Controllers and Endpoints

This code demonstrates how to use decorators to add metadata to a controller and its endpoints. The @ApiTags decorator assigns a tag to all endpoints in the controller, while @ApiOperation and @ApiResponse provide additional details about individual endpoints, such as the summary and expected response status and description.

@ApiTags('cats')
@Controller('cats')
export class CatsController {
  @Get()
  @ApiOperation({ summary: 'Get all cats' })
  @ApiResponse({ status: 200, description: 'Return all cats.' })
  findAll(): Cat[] {
    // logic to return all cats
  }
}

Defining DTOs (Data Transfer Objects)

This code snippet shows how to use the @ApiProperty decorator to define the properties of a DTO. This information is used by Swagger to generate accurate documentation for the expected request body when creating a new cat in the system.

export class CreateCatDto {
  @ApiProperty({ example: 'Whiskers', description: 'The name of the cat' })
  name: string;

  @ApiProperty({ example: 3, description: 'The age of the cat' })
  age: number;

  @ApiProperty({ example: 'Maine Coon', description: 'The breed of the cat' })
  breed: string;
}

Other packages similar to @nestjs/swagger

swagger-ui-express

This package is used to serve auto-generated swagger-ui generated API docs from express, similar to how @nestjs/swagger works with NestJS. It does not provide decorators but instead relies on a Swagger JSON or YAML file.

swagger-jsdoc

This package allows for the integration of Swagger using JSDoc comments directly in your code, rather than decorators. It's more suited for applications that are not using TypeScript or NestJS.

fastify-swagger

This is a Fastify plugin that provides similar functionalities for Fastify applications. It generates Swagger documentation for the Fastify API, similar to how @nestjs/swagger does for NestJS.

README

A progressive Node.js framework for building efficient and scalable server-side applications.

Description

OpenAPI (Swagger) module for Nest.

Installation

$ npm i --save @nestjs/swagger 

Quick Start

Overview & Tutorial

Migration from v3

If you're currently using @nestjs/swagger@3.*, note the following breaking/API changes in version 4.0.

The following decorators have been changed/renamed:

• @ApiModelProperty is now @ApiProperty
• @ApiModelPropertyOptional is now @ApiPropertyOptional
• @ApiResponseModelProperty is now @ApiResponseProperty
• @ApiImplicitQuery is now @ApiQuery
• @ApiImplicitParam is now @ApiParam
• @ApiImplicitBody is now @ApiBody
• @ApiImplicitHeader is now @ApiHeader
• @ApiOperation({ title: 'test' }) is now @ApiOperation({ summary: 'test' })
• @ApiUseTags is now @ApiTags

DocumentBuilder breaking changes (updated method signatures):

• addTag
• addBearerAuth
• addOAuth2
• setContactEmail is now setContact
• setHost has been removed
• setSchemes has been removed (use the addServer instead, e.g., addServer('http://'))

The following methods have been added:

• addServer
• addApiKey
• addBasicAuth
• addSecurity
• addSecurityRequirements

Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch

• Author - Kamil Myśliwiec
• Website - https://nestjs.com
• Twitter - @nestframework

License

Nest is MIT licensed.