Tema 15 · Interceptors & Swagger

15. Interceptors para Transformación/Logging y Documentación Automática con @nestjs/swagger

Mide tiempos de respuesta con RxJS tap(), envuelve respuestas JSON y genera un portal OpenAPI / Swagger UI interactivo con @ApiTags y @ApiProperty.

El Poder de los Interceptors y Observables RxJS

Los Interceptors están inspirados en la Programación Orientada a Aspectos (AOP). A diferencia de un Middleware tradicional, un Interceptor envuelve la ejecución del controlador como un flujo reactivo (Observable de RxJS), permitiéndote ejecutar lógica tanto antes de entrar al controlador como después, transformando el resultado con operadores como map(), tap() o timeout().

Documentación OpenAPI en Tiempo Real con @nestjs/swagger

Una API empresarial sin documentación interactiva frena a los equipos frontend y móviles. El módulo oficial @nestjs/swagger inspecciona tus controladores y clases DTO para generar automáticamente un portal Swagger UI en /api/docs:

npm i @nestjs/swagger
Decorador OpenAPI Dónde se coloca Resultado en Swagger UI
@ApiTags('Cursos') Sobre la clase @Controller('cursos') Agrupa todos los endpoints del controlador bajo una sección desplegable en Swagger.
@ApiBearerAuth() Sobre controladores o rutas protegidas Habilita el candado de seguridad para enviar el token JWT en las pruebas interactivas.
@ApiProperty({ example: ... }) Sobre cada propiedad de tus clases DTO Documenta el esquema JSON de entrada con tipos, restricciones y valores de ejemplo.

⚡ Interceptor de Envoltorio JSON y Configuración de Swagger UI

Transformación global de respuestas a { exito: true, datos } y montaje de SwaggerModule en /api/docs:

src/common/interceptors/transform.interceptor.ts
Solo lectura
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
  INestApplication,
} from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

export interface RespuestaEstandar<T> {
  exito: boolean;
  datos: T;
  timestamp: string;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, RespuestaEstandar<T>> {
  intercept(_context: ExecutionContext, next: CallHandler): Observable<RespuestaEstandar<T>> {
    return next.handle().pipe(
      map((datos) => ({
        exito: true,
        datos,
        timestamp: new Date().toISOString(),
      })),
    );
  }
}

// Función helper para activar Swagger en src/main.ts:
export function configurarSwagger(app: INestApplication): void {
  const config = new DocumentBuilder()
    .setTitle('Kilopolis Academia & SaaS API')
    .setDescription('Documentación interactiva OpenAPI 3.0 de los servicios RESTful de Kilopolis')
    .setVersion('1.0.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document);
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué operador de RxJS se utiliza dentro del método intercept() de un NestInterceptor cuando deseas transformar y envolver el objeto de respuesta que acaba de retornar el controlador?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar NestJS Framework Profesional y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.