@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
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 @ApiTagsDocumentBuilder breaking changes (updated method signatures):
addTagaddBearerAuthaddOAuth2setContactEmail is now setContactsetHost has been removedsetSchemes has been removed (use the addServer instead, e.g., addServer('http://'))The following methods have been added:
addServeraddApiKeyaddBasicAuthaddSecurityaddSecurityRequirementsNest 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,224,329 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
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.