Uso del paquete @nestjs/swagger para documentar tu API en NestJS

Documentación completa del paquete @nestjs/swagger

Para comenzar a utilizar Swagger con NestJS, es necesario instalar el paquete @nestjs/swagger usando npm o yarn:

npm install @nestjs/swagger
# o
yarn add @nestjs/swagger

Luego, importa el módulo SwaggerModule en tu módulo principal (normalmente AppModule) y configúralo de la siguiente manera:

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

// Dentro de tu función bootstrap()
const options = new DocumentBuilder()
  .setTitle('Título de tu API')
  .setDescription('Descripción de tu API')
  .setVersion('1.0')
  .addTag('tag')
  .build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup('api', app, document);

Al visitar '/api' en tu navegador, podrás ver la documentación de Swagger generada para tu aplicación.

Uso de decoradores para documentar tu API

Para documentar diferentes partes de tu API, como rutas, modelos de datos, parámetros y respuestas, puedes utilizar varios decoradores proporcionados por @nestjs/swagger.

Decoradores de rutas

@ApiOperation(): Se utiliza para describir una operación de ruta específica. Acepta un objeto que puede contener varias propiedades, como summary y description.

@Post()
@ApiOperation({ summary: 'Crea un nuevo usuario' })
async create(@Body() createUserDto: CreateUserDto) {
  return this.usersService.create(createUserDto);
}

@ApiTags(): Se utiliza para agrupar operaciones. Puede tomar uno o más argumentos que representan los nombres de las etiquetas.

@ApiTags('users')
@Controller('users')
export class UsersController {...}

Decoradores de respuestas

@ApiResponse(): Proporciona una descripción detallada de las posibles respuestas de una operación. Acepta un objeto que puede contener status, description, type y isArray.

@Get()
@ApiResponse({ status: 200, description: 'Se han obtenido los usuarios exitosamente.', type: User, isArray: true })
async findAll(): Promise<User[]> {
  return this.usersService.findAll();
}

Decoradores de modelos de datos

@ApiProperty(): Describe una propiedad en un modelo de datos. Puede aceptar un objeto que contiene description, type, example y más.

export class CreateUserDto {
  @ApiProperty({ description: 'El nombre del usuario.' })
  name: string;

  @ApiProperty({ description: 'El correo electrónico del usuario.' })
  email: string;
}

Decoradores de parámetros

@ApiQuery(), @ApiParam(), y @ApiBody(): Describe un parámetro de consulta, un parámetro de ruta y un parámetro de cuerpo, respectivamente.

@Get(':id')
@ApiParam({ name: 'id', required: true, description: 'El ID del usuario.' })
async findOne(@Param('id') id: string): Promise<User> {
  return this.usersService.findOne(+id);
}

@Post()
@ApiBody({ type: CreateUserDto })
async create(@Body() createUserDto: CreateUserDto) {
  return this.usersService.create(createUserDto);
}

Este es un vistazo a lo que puedes hacer con @nestjs/swagger. Puedes consultar la [document

ación oficial](https://docs.nestjs.com/openapi/introduction) para obtener una visión más completa y detallada.