@nestjs/swagger

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;
}