Implementar Swagger en un Proyecto NestJS

Swagger es una herramienta poderosa para documentar y probar APIs RESTful. En este post, te mostraré cómo implementar Swagger en un proyecto NestJS paso a paso.

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente:

• Node.js: Asegúrate de tener Node.js instalado. Puedes descargarlo Cómo instalar y usar NVM para gestionar versiones de Node.js en Ubuntu y Windows
• Te recomendamos configurar Entrono de trabajo para NestJS
• Realizar la Instalación de NestJS

Si no tienes un proyecto NestJS, puedes crear uno ejecutando:

npx @nestjs/cli new mi-proyecto
cd mi-proyecto

Instala las dependencias

Primero, necesitas instalar el paquete @nestjs/swagger y sus dependencias. Puedes hacerlo ejecutando el siguiente comando:

npm install @nestjs/swagger swagger-ui-express

Configura Swagger en tu Aplicación

Debes configurar Swagger en el archivo principal de tu aplicación, generalmente main.ts. A continuación, te muestro cómo hacerlo:

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Configuración de Swagger
  const config = new DocumentBuilder()
    .setTitle('API de Ejemplo')
    .setDescription('Documentación de la API')
    .setVersion('1.0')
    .addTag('users') // Etiqueta para agrupar los endpoints
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document); // Accede a la documentación en /api

  await app.listen(3000);
}
bootstrap();

Agrega Decoradores en tus Controladores

Para que Swagger genere la documentación automáticamente, debes agregar decoradores en tus controladores y DTOs. A continuación, se muestran ejemplos de cómo hacer esto.

Ejemplo de Controlador con Decoradores

// src/modules/user/user.controller.ts
import { Controller, Get } from '@nestjs/common';
import { UserService } from './user.service';
import { User } from './user.entity';
import { ApiTags, ApiResponse } from '@nestjs/swagger';

@ApiTags('users') // Etiqueta para agrupar en Swagger
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  @ApiResponse({ status: 200, description: 'Obtener todos los usuarios con sus roles.' })
  async findAllWithRoles(): Promise<User[]> {
    return this.userService.findAllWithRoles();
  }
}

Ejemplo de DTO con Decoradores

// src/modules/role/dto/create-role.dto.ts
import { IsString, IsNotEmpty } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreateRoleDto {
  @ApiProperty({ description: 'Nombre del rol' })
  @IsString()
  @IsNotEmpty()
  name: string;

  @ApiProperty({ description: 'Descripción del rol' })
  @IsString()
  @IsNotEmpty()
  description: string;
}

Accede a la Documentación de Swagger

Una vez que hayas configurado todo, puedes iniciar tu aplicación con:

npm run start

Luego, accede a la documentación de Swagger en tu navegador mediante la siguiente URL:

http://localhost:3000/api