@nestjs/swagger
Advanced tools
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.
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;
}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.
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.
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.
A progressive Node.js framework for building efficient and scalable server-side applications.
OpenAPI (Swagger) module for Nest.
$ npm i --save @nestjs/swagger
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.
Nest is MIT licensed.
FAQs
Nest - modern, fast, powerful node.js web framework (@swagger)
The npm package @nestjs/swagger receives a total of 1,667,370 weekly downloads. As such, @nestjs/swagger popularity was classified as popular.
We found that @nestjs/swagger demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.