General Discussion

[underfisk]

This issue will be the main topic for discussion regarding what this plugin should contain and how. Everyone is welcomed to contribute, i didn't have yet much time to set up some PR guidelines but soon i will, meanwhile i would like to hear how you guys imagine seeing async api integrated with Nestjs. What i'm doing right now is creating a similar API as nestjs swagger module offers but there are a few differences that we needed to address in different ways with the Async API specification

Channels

AsyncAPI tell us that a channel must be a sort of component that relates with the server, therefore i decided to create 2 decorators for controller methods that will enforce the developer to specify the channel name and payload type but i'll show in a second what i mean by "specifying". A channel is basically what we call a "pattern" in nestjs microservices, i could read the pattern from the decorator but that can take away the possibility to use HTTP controller (async api also does support REST) so i would like to hear ideas on how to approach this in a gentle way. Since channels are the patterns i will ask for the name of the channel (i could have a decorator with the name but that's just extra boilerplate) and therefore you must guarantee that the channel is valid, there's no way of referencing it yet. The type will pretty much work as Swagger, you can pass a DTO (but here i hope i can support generics which is something it lacks), and depending on the decorator (Consumer = Subscribe or Publisher = Publish) it will be the message payload A side book regarding why the channel is not a decorator for the controller class is because there are use cases where your controller can handle multiple patterns and having a channel per controller would restrict that, therefore i decided that each method/event handler will assume the responsibility of providing the channel name

Publisher/Consumer (duplex support)

This one is pretty much straightforward, I have in mind to allow a microservice handler to consume and publish, you still need to specify the name of the channel aka pattern and in this matter it makes more sense having the channel name being specified because it will probably not publish the event to the same channel (in cases like RabbitMQ it does send back the response to the same endpoint but you can also publish to a different broker/channel)

Schema References

AsyncAPI allows you to create custom schema models but this is not 100% like OpenAPI, therefore I will support the reference name as string and custom class type (It has to be decorated with AsyncSchema decorator in order to gather its metadata)

Validations out-of-the-box

If you have used AsyncAPI before it throws usually a lot of generic errors even for things such as "invalid URLs". I decided to add some custom validation wrapped in front of the document/contract builder that will help you identify the mistake, that is something the AsyncAPI team is probably working on at their parser but until then, we'll have some little help

Decorators in mind

Here is a quick overview with the current decorators i do have in mind and settled, this project was already created months ago for personal usage but i decided to look at nestjs swagger module and create a close codebase (so this plugin can be possibly included into an official package and interchanged with swagger decorators)

• AsyncConsumer: Method decorator that generates channel subscribe property (similar to ApiOperation in swagger module)
• AsyncPublisher: Method decorator that generates channel publish property (similar to ApiResponse in swagger)
• AsyncMessage: Class decorator for custom DTO classes that provides extra metadata and tells nestjs async API that its a model to be used as a payload for AsyncConsumer and AsyncPublisher (if the type passed to consumer/publisher does not contain this decorator, it will throw an error)
• AsyncProperty: Property decorator as ApiProperty (swagger module)

The project will be uploaded soon so anyone can contribute, meanwhile I welcome everyone to give some thoughts about this project and help if possible. Let's make our lives easier!

[rluvaton]

Great idea, and I'll try to help (I'm a little busy so I can't promise that I'll actively contributing, but I'll try to find some time slots to help).

How should we support content types that aren't easy to model, binary data for example?

Also, I believe that AsyncAPI will mainly be in use in a microservices architecture which is a decentralized architecture. How should we model the entire api which is split across different projects?

[underfisk]

Nice questions indeed, i can try to address them in different topics

1. Content types you can specify, i have that already in mind, by default its "application/json" so its expects to be as json but as i called it "Contract" instead of "Document" by a specific reason, your API will expose a contract rather than a json document, therefore you are responsible to tell the consumer the protocol he needs to use. Right now i use reflection like Swagger module does to build up the schemas and it will convert to the model of Async API which is agnostic to the content type, so you just pass the content type to the decorator if its not a JSON and voila. I'm not sure if this answers your question but i can show you a code example if you need
2. GraphQL kinda had this problem on Nestjs and that's where Federations came in. Right now i'm the only one working on the project and the scope i had in mind was for the service itself, in microservices you usually have service discovery or a service mesh that will expose endpoints of documentation but usually, the gateway of service discovery is an app and so that app can "Federate" multiple documentation endpoints, this is probably what you are looking for, a proxy for the other services documentation.
3. Microservices models are independent, therefore you usually end up with duplicated models and that's why microservices are not typically used for small teams, it will require a team to be dedicated and in-sync with its service dependencies, therefore you should build your documentation (be it swagger or async api) on each service

I made these 3 topics to try to answer your doubts, not sure if I'm missing something but let me know

[garethhcoleman]

I'd like to help, I'm an intermediate programmer (also new to js/ts) struggling to build my first api with both RESTful and MQTT parts using nestjs. I'm keen to bring the sort of functionality from swagger across to the message part of my api - mostly documentation but doing quick tests is also really handy. I think my contributions will be most valuable to test candidate builds and or write documentation etc - but perhaps I will also be able to help with development and bugfixing?

[underfisk]

@garethhcoleman Every help is welcomed, right now i haven't uploaded yet the project because i'm preparing some generic adjusts (it was previously agnostic to one of my projects) but i'm pretty sure this will help also in your use case I'll open soon the PR rules and generation of documentation but right now i'm kinda tied on time, i'll keep this updated as soon as i can. Meanwhile stay tune

[arnautg]

I'm also interested in contributing to this feature so we keep in touch I'll be watching 👀

[0xvbetsun]

I'm also interested in contributing to this feature. If nobody minds, I'd like to finish the setup of the project like adding CI, renovate/dependabot, etc

[underfisk]

I've been a little bit of this project, as soon as I have more time I'll continue the project and make sure it's up to date with async API standards. Any contributions are welcomed

[ChoSeoHwan]

I'm currently working on a project using nestjs and socket io. I'd like to use this project for documentation purposes, but it's been 6 months since uploaded the current project, so I'm wondering if it's still in development.

I have also tried the flamewow/nestjs-asyncapi library, but it is difficult to use because there are many features that are not yet supported.

I hope I can use this project

[skrilax91]

Hi ! is this project dead ? i try to find a good asyncApi doc generator and nobody seems to get enough interest to maintain a project