nestjs-asyncapi

Description

AsyncApi module for Nest.

Generate AsyncApi documentation (for event-based services, like websockets) in a similar to nestjs/swagger fashion.

Live Preview

AsyncApi playground

Installation

full installation (with chromium)

$ npm i --save nestjs-asyncapi

nestjs-async api package doesn't require chromium (which is required by asyncapi lib), so u can skip chromium installation by setting PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true environment variable.

$ PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm i --save nestjs-asyncapi

Quick Start

Include AsyncApi initialization into your bootstrap function.

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

    const asyncApiOptions = new AsyncApiDocumentBuilder()
        .setTitle('Feline')
        .setDescription('Feline server description here')
        .setVersion('1.0')
        .setDefaultContentType('application/json')
        .addSecurity('user-password', {type: 'userPassword'})
        .addServer('feline-ws', {
            url: 'ws://localhost:3000',
            protocol: 'socket.io',
        })
        .build();

    const asyncapiDocument = await AsyncApiModule.createDocument(app, asyncApiOptions);
    await AsyncApiModule.setup(docRelPath, app, asyncapiDocument);

    // other bootstrap procedures here

    return app.listen(3000);
}

AsyncApi module explores Controllers & WebSocketGateway by default. In most cases you won't need to add extra annotation, but if you need to define asyncApi operations in a class that's not a controller or gateway use the AsyncApi class decorator.

Mark pub/sub methods via AsyncApiPub or AsyncApiSub decorators

class CreateFelineDto {
    @ApiProperty()
    demo: string;
}

@Controller()
class DemoController {
    @AsyncApiPub({
        channel: 'create/feline',
        message: {
            payload: CreateFelineDto
        },
    })
    async createFeline() {
        // logic here
    }

    @AsyncApiSub({
        channel: 'create/feline',
        message: {
            payload: CreateFelineDto
        },
    })
    async createFeline() {
        // logic here
    }
}