How to Use

Get NestJS Events Swagger up and running in your NestJS application in just a few steps.

Install the Package

Install NestJS Events Swagger using npm or your preferred package manager.

terminalbash

npm install nestjs-events-swagger

Import the Module in NestJS

Import and configure the EventsSwagger module in your application's root module. This example shows how to set it up with Kafka transport using async configuration.

app.module.tstypescript

import { Module } from '@nestjs/common';
import { ConfigService, ConfigModule } from '@nestjs/config';
import { EventsSwagger, EventSwaggerTransport } from 'nestjs-events-swagger';

@Module({
  imports: [
    EventsSwagger.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => {
        return {
          uiPath: 'events-swagger-docs',
          transport: {
            transport: EventSwaggerTransport.KAFKA,
            brokers: [configService.get('KAFKA_BROKERS')],
          },
          description: "My API Events Documentation",
        };
      },
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

This configuration sets up NestJS Events Swagger with async factory pattern, allowing you to inject services like ConfigService for dynamic configuration.

Configuration Options

NestJS Events Swagger provides various configuration options to customize the module to your needs:

uiPathThe route path where the Swagger UI will be accessible (e.g., 'events-swagger-docs' makes it available at /events-swagger-docs)
transportTransport configuration object containing the transport type and its specific options
transport.transportThe event transport type (e.g., EventSwaggerTransport.KAFKA, EventSwaggerTransport.WEBSOCKET)
transport.brokersArray of broker addresses (for Kafka transport)
descriptionA description displayed in the Swagger UI header to describe your events API

Document Events with @ApiEvent

Use the @ApiEvent() decorator to document your event handlers. This decorator tells NestJS Events Swagger about your event consumers and their expected payload schemas.

user.controller.tstypescript

import {
  ApiEvent,
  EventSwaggerTransport,
} from 'nestjs-events-swagger';
import { EventPattern, Payload } from '@nestjs/microservices';

@ApiEvent({
  transport: EventSwaggerTransport.KAFKA,
  pattern: 'my-topic',
  payload: { type: UserCreatedBodyParamDto },
})
@EventPattern('my-topic')
async handleUserCreated(@Payload() data: UserCreatedBodyParamDto) {
  console.log('Consumer received from my-topic:', data);
  return;
}

@ApiEvent Options

transportThe transport type for this event handler (e.g., EventSwaggerTransport.KAFKA). Can be set to null if not applicable.
patternThe topic or pattern name that this handler subscribes to. Can be set to null if not applicable.
payloadOptional payload configuration object describing the expected event data structure.
payload.typeA class (DTO) constructor that defines the schema of the payload. Used to generate documentation and validate test payloads.
payload.isArrayOptional boolean indicating whether the payload is an array of the specified type. Defaults to false.

Bootstrap Configuration

To access the Swagger docs page, your application must listen on a port (not just start microservices). Here's the required bootstrap configuration:

main.tstypescript

import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { AppModule } from './app.module';

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

  app.connectMicroservice<MicroserviceOptions>(
    {
      transport: Transport.KAFKA,
      options: {
        client: {
          brokers: ['localhost:9092'],
        },
        consumer: {
          groupId: 'my-consumer-group',
        },
        run: {
          autoCommit: true,
        },
      },
    },
    { inheritAppConfig: true },
  );

  app.enableCors();
  await app.startAllMicroservices();
  
  // IMPORTANT: You must also listen on a port to serve the Swagger UI
  await app.listen(3001);
}

bootstrap();

Important: The app.listen() call is required for the Swagger UI to be accessible. Without it, only the microservices will start, but the HTTP endpoints (including the Swagger docs) won't be available.

Start Your App

Start your NestJS application as usual. Once the app is running, you can access the NestJS Events Swagger UI in your browser.

terminalbash

npm run start:dev

Tip: Once your app is running, navigate to http://localhost:3001/events-swagger-docs (or your configured uiPath) to access the Events Swagger UI and start interacting with your events.

Need More Help?

Have questions, need assistance, or want to share feedback? Feel free to reach out for support and I'll be happy to help you get the most out of NestJS Events Swagger.

Contact Support