Add AsyncAPI support

[rluvaton]

Feature Request

Please add AsyncAPI support for documenting microservice events that been published

Is your feature request related to a problem? Please describe.

There is no support for documenting event-based messages (like swagger for HTTP)

Describe the solution you'd like

Add support to AsyncAPI as same as Swagger

[stevenj]

I am confused what this is actually asking for. My entire AsyncAPI documented async protocol is what i would call "event based" and i didn't notice anything missing (except the words Pub and Sub are not intuitive for event based, but thats a minor inconvenience).

[rluvaton]

@stevenj From what you wrote I understand that I can document my Pub-Sub events using AsyncAPI?
Do you have any documentation about this? I haven't found any in the official website...

[stevenj]

@rluvaton Well, AsyncAPI just defines how you define messages, what meaning you give to "channels", and "pub/sub" is up to you. So the first thing i did was said, for my doc, defined a "channel" to mean "a group of messages that are tightly related". Basically in my spec that means, a command and its reply, or a status update and its acknowledgement. etc etc. So usually there are two messages in a channel, but sometimes more (rarely more than 3 operation, reply and error).
I then declared what PUB and SUB meant. So, for me "PUB" is messages originating at the server (AWS lambda micro services in our implementation, through the AWS Websocket gateway) and destined for the remote device. And "SUB" is messages that originate in the remote devices and are destined for the service.

Because it's asynchronous and stateless, the protocol is designed such that replies to messages can arrive out of sequence and how that's handled but that's up to you at the protocol level.

The protocol level just defines the json message which encapsulates each message and how it is to be interpreted and what operation is to be done on it, what replies are expected from it.

We don't auto generate code from this, we simply use it for documentation but its working well.

I can't really share my API because its proprietary to the company. All of this extra information i discussed here which isn't in AsyncAPI proper is documented inside descriptions at the appropriate level. My Top Level document description contains a section called "Documentation Conventions" which details these conventions and they form part of the protocol.

The main difference between AsyncAPI and Swagger is it doesn't have built in pairing of messages and replies (because that's synchronous). So when you have asynchronous pairing, as i do, you define that with individual discreet messages and then relate them together using Channel, PUB/SUB and ancillary documentation in the message descriptions (I have links to the replies or the messages which trigger the replies in the description for example.)

[derberg]

@rluvaton I think you need to provide more details to the initial request. I'm not nestjs user, but AsyncAPI maintainer. My assumption was that you are requesting support for AsyncAPI the way OpenAPI is supported -> https://docs.nestjs.com/openapi/introduction. Looking at comments from @stevenj, I have impression your request got misunderstood. These are just assumptions though 😄 Just keep in mind folks that if someone will work on this, AsyncAPI folks are all yours if you need to consult something 😉 https://www.asyncapi.com/slack-invite/

[auerbachb]

My assumption was that you are requesting support for AsyncAPI the way OpenAPI is supported -> https://docs.nestjs.com/openapi/introduction.

I am very interested in exactly this being able to generate and host the OpenAPI documentation from within nest with decorators as the OpenAPI documentation can be done. (However, it would also be interesting to integrate the generator so that the websocket generation inside NestJS conformed to the AsyncAPI format/made use of the generator there...which I assume is considerable more work...both are a bunch of work)...

In the meantime...perhaps just suggestions on where to put this in the folder structure could be a start...I guess my plan now is to generate the docs and then just host them as a static file from my NestJS app.

[kamilmysliwiec]

I would be more than happy to see the Async API integration, but we currently don't have enough time to start working on a new package (and actively maintaining it down the road). If anyone is interested in creating and sharing the integration with everyone as an OSS library (for example, by forking the @nestjs/swagger or alternatively, writing it from scratch), that would be amazing!

Since we don't plan to get back to this feature in the foreseeable future, let me close this issue.

[underfisk]

@kamilmysliwiec I might have the solution for this problem, I have been developing a module like @nestjs/swagger for async API due to the high internal usage, I might publish it and link it here if anyone is interested in

[rluvaton]

@kamilmysliwiec I might have the solution for this problem, I have been developing a module like @nestjs/swagger for async API due to the high internal usage, I might publish it and link it here if anyone is interested in

Is it open source? So maybe we can contribute

[underfisk]

@rluvaton Yes it is, i'll publish it real soon as i see now that people is interested in. There are some caveats with support for Typescript from asyncapi team, therefore i had to develop all types and some other features

[underfisk]

As said earlier, I had a personal project for async-api and nestjs from some time ago, a few days ago I decided this could potentially be similar to the swagger package, therefore, I decided to create the github repository so everyone can share thoughts and discuss implementation. Contributions would be welcomed too since this is a bit time consuming
Here is the link to the topic issue: underfisk/nestjs-asyncapi#1

@kamilmysliwiec I hope it is okay to publish here to repository link, as promised before i will try to keep a clean and codebase similiar to swagger so it can be pottently included as part of microservices documentation/specification

[ivamuno]

Hi,
I have created a beta version for AsyncAPI (also, it has support for OpenAPI) using my own extension for redoc: https://github.com/ivamuno/nestjs-openapi.
The decorators have been created for documentation only, decoupling code from the documentation, means, the existing MessagePattern decorator is ignored. Why? For example, I am using "@golevelup/nestjs-rabbitmq" instead nestjs one.
If you have any suggestions please let me know.
Regards

[underfisk]

@ivamuno I'm not sure exactly, in the project I'm developing for AsyncAPI it is agnostic to the transport, it doesn't need to import rabbitmq or kafka, you provide whatever transport you need but i see that you are trying to bring it as a built in feature which i don't exactly how to answer on that

[almarro1]

There is also this library in npm (https://www.npmjs.com/package/asyncapi-decorator) which generates the yml definition file. Has some limitations and bugs, but does the trick

[underfisk]

@almarro1 I have already the decorators created pretty much based on Swagger module, it will be first-class supported for nestjs which would make more sense

[almarro1]

@underfisk I know, and I really like your approach. Just wanted to mention it in case someone needs a working solution asap.
Really looking forward to seeing your project in action

[underfisk]

@almarro1 i did saw that plugin but it wasn't going to work so well with Nestjs. Right now i don't have yet much time but i have some local development advanced for the plugin, anytime soon it will be on because i even need it for my personal projects

[flamewow]

I'm working on https://github.com/flamewow/nestjs-asyncapi
if you are still interested - give it a shot

[olawalejuwonm]

I'm working on https://github.com/flamewow/nestjs-asyncapi if you are still interested - give it a shot

Can this be part of nestjs ?