AsyncAPI Cheatsheet feedback

[derberg]

First of all huge thanks for the work you did for the community and for sharing the knowledge about AsyncAPI with others at conferences. AsyncAPI Conference room was full of cheat sheet posters 😄

Let me pay back with some feedback about cheat sheet.

As a typical Polish guy, I will focus on possible improvements only 😆 . With some of you I already shared the positive feedback on how I like how you managed to represent complex info on a single page cheat sheet - we failed in this field with AsyncAPI cheatsheet we worked on before.

• small bug in Operations section, the $ref for example message. It is #/messages/userData but there is no root level messages object. You need to point to specific message (you don't have to, in the end it is optional) under the channel you reference. Correct value should be #/channels/userSignedUp/messages/userSignedUp (of course if you want to somehow relate to data from Channels section
• if above is right and aligned with your idea for cheat sheet, then $ref for channel has error as well, should be #/channels/userSignedUp
• General Information I think it is useful to add some simple comment to the servers section. Explain that it is quite different in the case of AsyncAPI, compared to OpenAPI. In the case of websocket, the server might point to the service address, but in other architectures, with other protocols, server can be a broker detail. Not many people realize that. In the cheat sheet that we did, we have diagram that address pub/sub model, so we use that to explain to people, in your case you need at least a sentence in my opinion
• you have no mention of extensions but I guess it is because of the space limit 😄 but for you would make sense to put it there as you support some custom extensions in bump.sh

So as you can see, some minor suggestions to amazing work you did!

[grossyoan]

Hey @derberg,

Thanks for your warm feedback, it really helps!
And we are thrilled to see that it's useful for the community. We did it with love 💙

We updated the cheatsheet just moments before your message, reworking the $ref and some other small typos. You can find it here

We totally agree about the protocols: we had to choose one, but as you say, some parts of the specification are specific to one protocol or another. Now that there's a global v1, we are considering creating specific cheatsheets for the different protocols.

Regarding custom extensions, it was both a space limit and the desire to focus on what are really the fundamentals of writing a good AsyncAPI definition for the V1 of the cheatsheet.

Have a good day, and thanks again! 🙏

[derberg]

no worries,

just one thing, in Operations section you need to fix the message $ref as now it is changed to #/components/messages/userData and MUST be #/channels/userSignedUp/messages/userData

Specification is very conservative in this area:

It MUST contain a subset of the messages defined in the channel referenced in this operation, and MUST NOT point to a subset of message definitions located in the Messages Object in the Components Object or anywhere else

[grossyoan]

Thanks a lot, we updated it with this feedback as well!