{"id":296,"date":"2026-06-18T23:34:51","date_gmt":"2026-06-19T04:34:51","guid":{"rendered":"https:\/\/jeffsantillan.com\/blog\/?p=296"},"modified":"2026-06-19T00:20:08","modified_gmt":"2026-06-19T05:20:08","slug":"nestjs-uso-de-swagger-para-documentacion","status":"publish","type":"post","link":"https:\/\/jeffsantillan.com\/blog\/nestjs-uso-de-swagger-para-documentacion\/","title":{"rendered":"Nestjs uso de Swagger para documentaci\u00f3n"},"content":{"rendered":"\n

Swagger es una herramienta que genera documentaci\u00f3n interactiva de tu API autom\u00e1ticamente. En lugar de documentar manualmente cada endpoint en un Word o Notion, Swagger lee tu c\u00f3digo y genera una interfaz web donde cualquier developer puede ver y probar la API sin usar Postman o PowerShell<\/p>\n\n\n\n

Extendiendo el proyecto de Usuario: Enlace<\/a><\/p>\n\n\n\n

Podemos incluirle el Swagger para documentar la API<\/strong>.<\/p>\n\n\n\n

instalar<\/p>\n\n\n\n

npm install @nestjs\/swagger<\/code><\/pre>\n\n\n\n
Es asi que al archivo de main.ts le voy a incluir o habilitar Swagger, hay que importar en el main y agregar las siguientes lineas<\/p>\n\n\n\n
import { DocumentBuilder, SwaggerModule } from '@nestjs\/swagger';\n\n\/\/ Swagger\n  const config = new DocumentBuilder()\n      .setTitle('Sistema de Usuario API')\n      .setDescription('API para gestion de usuarios')\n      .setVersion('1.0')\n      .addTag('usuario')\n      .build();\n\n  const document = SwaggerModule.createDocument(app, config);\n  SwaggerModule.setup('api', app, document);\n<\/code><\/pre>\n\n\n\n
Quedando el archivo main.ts de la siguiente manera.<\/p>\n\n\n\n
import { NestFactory } from '@nestjs\/core';\nimport { AppModule } from '.\/app.module';\nimport { ValidationPipe } from '@nestjs\/common'; \/\/ Validator\nimport { DocumentBuilder, SwaggerModule } from '@nestjs\/swagger';\n\nasync function bootstrap() {\n  const app = await NestFactory.create(AppModule);\n\n  app.useGlobalPipes(new ValidationPipe({\n    whitelist: true, \/\/ Elimina los campos que no estan en los DTOs\n    forbidNonWhitelisted: true, \/\/ Lanza un error si llegan campos extra\n    transform: true,  \/\/ Transforma tipos automaticamente.\n  }));\n\n  \/\/ Swagger\n  const config = new DocumentBuilder()\n      .setTitle('Sistema de Usuario API')\n      .setDescription('API para gestion de usuarios')\n      .setVersion('1.0')\n      .addTag('usuario')\n      .build();\n\n  const document = SwaggerModule.createDocument(app, config);\n  SwaggerModule.setup('api', app, document);\n\n  await app.listen(process.env.PORT ?? 3000);\n}\nbootstrap();<\/code><\/pre>\n\n\n\n
Luego hay que decorar los DTOs, importando el ApiProperty y utilizar el decorador en cada campo con la estructura de datos con example y description.<\/p>\n\n\n\n
import { IsEmail, IsNotEmpty, IsString, IsNumber, Min, Max } from 'class-validator';\nimport { Type } from 'class-transformer';\nimport { ApiProperty } from '@nestjs\/swagger';<\/strong>\n\nexport class CreateUsuarioDto {\n\n    @ApiProperty({ example: 'Jefferson', description: 'Nombre del usuario'})<\/strong>\n    @IsNotEmpty({message: 'El nombre es obligatorio'})\n    @IsString()\n    nombre!: string;\n\n    @ApiProperty({ example: 'jeffsp@gmail.com', description: 'Correo del usuario'})<\/strong>\n    @IsNotEmpty()\n    @IsEmail({}, {message: 'Email inv\u00e1lido'})\n    email!: string;\n\n    @ApiProperty({ example: '30', description: 'Edad del usuario'})<\/strong>\n    @IsNumber()\n    @Min(18, {message: 'Debe de ser mayor de 18'})\n    @Max(99)\n    @Type( () => Number) \/\/Aqui se utiliza la clase transform explicitamente.\n    edad!: number;\n}<\/code><\/pre>\n\n\n\n
Finalmente, mejorar el controlador con: ApiTags, ApiOperation y ApiResponse<\/p>\n\n\n\n
import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs\/common';\nimport { UsuarioService } from '.\/usuario.service';\nimport { CreateUsuarioDto } from '.\/dto\/create-usuario.dto';\nimport { UpdateUsuarioDto } from '.\/dto\/update-usuario.dto';\nimport { ApiTags, ApiOperation, ApiResponse } from '@nestjs\/swagger';<\/strong>\n\n@ApiTags('usuario')<\/strong><\/em>\n@Controller('usuario')\nexport class UsuarioController {\n  constructor(private readonly usuarioService: UsuarioService) {}\n\n  @ApiOperation({summary:'Crear nuevo usuario'})\n  @ApiResponse({status:201, description:'Usuario creado'})\n  @ApiResponse({status:400, description:'Datos inv\u00e1lidos'})<\/em><\/strong>\n  @Post()\n  create(@Body() createUsuarioDto: CreateUsuarioDto) {\n    return this.usuarioService.create(createUsuarioDto);\n  }\n\n  @ApiOperation({summary: 'Listar todos los usuarios'})\n  @ApiResponse({status:200, description:'Lista de usuarios'})\n  @Get()\n  findAll() {\n    return this.usuarioService.findAll();\n  }\n\n  @ApiOperation({summary: 'Obtener usuario por ID'})\n  @ApiResponse({status:200, description: 'Usuario encontrado'})\n  @ApiResponse({status:404, description: 'Usuario no encontrado'})\n  @Get(':id')\n  findOne(@Param('id') id: string) {\n    return this.usuarioService.findOne(+id);\n  }\n\n  @ApiOperation({summary: 'Actualizar usuario'})\n  @ApiResponse({status: 200, description: 'Usuario actualizado'})\n  @Patch(':id')\n  update(@Param('id') id: string, @Body() updateUsuarioDto: UpdateUsuarioDto) {\n    return this.usuarioService.update(+id, updateUsuarioDto);\n  }\n\n  @ApiOperation({summary: 'Eliminar usuario'})\n  @ApiResponse({status: 200, description: 'Usuario Eliminado'})\n  @Delete(':id')\n  remove(@Param('id') id: string) {\n    return this.usuarioService.remove(+id);\n  }\n}<\/code><\/pre>\n\n\n\n
Descripci\u00f3n de decoradores:<\/p>\n\n\n\n