Examples needed
schw4rzlicht opened this issue · 14 comments
Hey there!
I'm currently documenting a proprietary API using AsyncAPI and want to generate client code using the template.
I struggle with it because of the lack of websocket examples for AsyncAPI and how to use the generated code. What I learned so far is that there is only one "channel" when using web sockets with multiple messages to publish and subscribe to in most cases.
In my understanding, this template only generates one function to send messages for publish and subscribe sections. So building listeners for incoming messages and send functions for outgoing messages is still to be done manually, right? What is the whole point of generating node.js code then?
Is this template only meant as an example for how to build a template on your own which covers your needs?
Then again: I am not sure how to exactly describe an API using AsyncAPI in the first place. E.g. I do have a query parameter which is always present and never changes. But where would I define that? I tried bindings in the server object and bindings in the channel object but the only thing that seems to look right is putting it either into the server URL which then breaks the channel or using it as the channel name which breaks the generated code.
Could someone please shed some light into the dark? Thanks very much! :)
Welcome to AsyncAPI. Thanks a lot for reporting your first issue.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
Hi @schw4rzlicht. I'm sorry to hear you're struggling with this. We're in the process of rebuilding our docs and adding more functionality to our code generators. This template was really an example and hasn't been taken care of much. That doesn't mean it's abandoned. We'll have to work on it soon and probably make it client only because we already have server-side generation for WS on https://github.com/asyncapi/nodejs-template.
So building listeners for incoming messages and send functions for outgoing messages is still to be done manually, right? What is the whole point of generating node.js code then?
The purpose of this template is to have them. We just haven't worked on it yet. A PR would be appreciated 😊
Then again: I am not sure how to exactly describe an API using AsyncAPI in the first place. E.g. I do have a query parameter which is always present and never changes. But where would I define that? I tried bindings in the server object and bindings in the channel object but the only thing that seems to look right is putting it either into the server URL which then breaks the channel or using it as the channel name which breaks the generated code.
Channel bindings are the right place for this information: https://github.com/asyncapi/bindings/tree/master/websockets. Again, it just doesn't work because this template needs some love.
Here's an example using WebSockets: https://github.com/asyncapi/generator/blob/master/test/docs/ws.yml
I hope this helps. This is all we got so far in terms of documentation but stay tuned, we're working on great docs and guides as well as improving the templates.
Thank you so much for your help!
Based on your information I started to work on the template with the goal to PR when I'm done.
It works out so far, the only challenge is to understand and use Nunjucks the right way. What's not clear to me is how resolving of messages and their names should work.
For channels I can easily do {%- for channelName, channel in asyncapi.channels() %} but not for messages since asyncapi.channels() returns an object while channel.subscribe().messages() returns an array, so I need to get the name (a.k.a. the key of the underlying YAML) of the message from every message object.
message.name() is empty; I could use message._json.x-parser-message-name for that but a) this looks bad and b) when printing it using {{ }} it only prints NaN. Is there a better way?
EDIT: Find my WIP in this fork.
EDIT 2: Sorry for my confusion, I figured that name needs to be set in the YAML of course to be retrievable by message.name().
So far I am able to generate listener code, I just need to implement validation logic for the message handlers still. Then I'd generate code for sending messages.
The only thing I would need is feedback. I went for an event-based approach using EventTarget and ES6-Modules. I also threw out the server-code. Would you consider a PR with such radical changes or should I maintain it as its own template?
EDIT 3: Okay, it works in browsers and in node now. I removed ES6-modules b/c of compatibility issues again and use CommonJS now. I use browserify to bundle dependencies for the browser. EventTarget is of course not supported by node so I use EventEmitter which is bundled for browsers as well. I use isomorphic-ws to make sure that websockets work in both environments.
I did not implement generation for sending logic since I don't think this would be beneficial for users. Validation of incoming messages is done by ajv using the payload objects.
This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️
This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️
@schw4rzlicht I'm interested in using your fork, and potentially helping you get it to the point it could be merged into this repo (disclaimer: I am not a developer or maintainer of this repo).
Are you still working on it?
This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️
@aphilpott Sorry for my late reply. Currently, I am not working on it any more due to the lack of feedback on the issue and changes in my field of work. Please feel free to use my fork and go from there, I might chime in at a later point again.
fyi @schw4rzlicht and @aphilpott, I will work on this topic in January (asyncapi/spec#253 (comment)). Sorry we are so late here but the last 6months was a hell of a ride
still on my todo list, there was just a shift of priorities and because of AsyncAPI partnership with Postman we focused first on setting up open governance model and handing over the spec into the foundation. Sorry for the delay
This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️
@schw4rzlicht @aphilpott
Hi folks. I recently fixed some bugs in the template and added the generation of some more stuff. The latest 0.9 release has those improvements. In the next 2 weeks, I'm gonna publish an article explaining what can be done with this template and the example that I used.
Bear in mind though that for now, this template doesn't support use case with single channels having oneOf multiple messages. It always reads first message from the list, so the use case is, multiple channels with single message each.
This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️