NestJS AsyncAPI module - generate documentation of your event-based services using decorators
npm install cs-nestjs-asyncapiGenerate AsyncApi documentation (for event-based services, like websockets) in a similar
to nestjs/swagger fashion.
full installation (with chromium)
``bash`
$ 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.
`bash`
$ PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm i --save nestjs-asyncapi
Include AsyncApi initialization into your bootstrap function.
`typescript
async function bootstrap() {
const app = await NestFactory.create
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, and EventsHandler (from @nestjs/cqrs) by default.AsyncApi
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, gateway, or event handler use the class
decorator.
Mark pub/sub methods via AsyncApiPub or AsyncApiSub decorators
`typescript
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
}
}
// EventHandler example (CQRS)
@EventsHandler(FelineCreatedEvent)
class FelineCreatedHandler implements IEventHandler
@AsyncApiPub({
channel: 'feline.created',
message: {
payload: FelineDto,
description: 'Event published when a new feline is created',
},
})
handle(event: FelineCreatedEvent) {
// publish event to message broker
}
}
``
For more detailed examples please check out https://github.com/flamewow/nestjs-asyncapi/tree/main/sample sample app.