docs: new guide for message validation #1005
Conversation
starlightknown
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site settings. |
starlightknown
changed the title
|
|
@akshatnema Heyo, can you help Karuna here? She is trying to figure out why her builds are failing and not generating the Netlify preview 😄✌🏽 |
There was a problem hiding this comment.
@starlightknown You forgot the escape characters before the string literal where you want to highlight the text.
Co-authored-by: Akshat Nema <76521428+akshatnema@users.noreply.github.com>
Co-authored-by: Akshat Nema <76521428+akshatnema@users.noreply.github.com>
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-1005--asyncapi-website.netlify.app/ |
|
Thanks a lot! @akshatnema I'd still be searching for { because that's what logs showed |
There was a problem hiding this comment.
@starlightknown I re-wrote your guide because:
- there was a lot of duplicate content, all over the place (this made it hard to follow)
- the writing was too verbose; for guides/tutorial steps, you should always focus on starting sentences with verbs for each individual action
- there were many grammar and punctuation errors (You must always run your written content through Grammarly first BEFORE you request reviews)
TO DO:
- I think we have indentation issues in the code snippets added. Please go through all the code snippets and fix as needed 😄✌🏽.
- Are there "additional resources" we could add to help the user? If so, please add them to the end of your doc (I already added that header section)
|
Hey @derberg, this is ready for technical review! I made a draft update, so I hope I didn't add technical mistakes 😂 |
| title: Validate Messages/Events | ||
| description: This guide explains two ways to validate messages/events in AsyncAPI documents. |
There was a problem hiding this comment.
| title: Validate Messages/Events | |
| description: This guide explains two ways to validate messages/events in AsyncAPI documents. | |
| title: Validate Messages/Events in runtime | |
| description: This guide explains different use cases for messages/events validation using AsyncAPI. |
This should be a guide where we just explain different ways of doing things. Now it sounds like the only tools out there are asyncapi-validator and event gateway. The goal should not be to promote them and explain how to use them (that for example Nodejs is needed, or that npm i must be run. The goal is to highlight that there are many different ways people approach message validation.
you can start with a diagram showing producer-broker-producer and say "blabla validation can occur on any stage of the flow" and then:
- section: Validation inside producer and consumer -> It could start with the same diagram, but somehow marked what components are critical for that section. And you explain that validation of incoming and outgoing messages can be an integral part of the application. Your AsyncAPI file should contain descriptions of payload schemas, so you can read these in your application, and validate messages that are consumed by the application and also produced. -> and then
asyncapi-validatorcomes into play, as just one example of how this could be done. That there is Nodejs library that allows you to pass AsyncAPI file to it, and get validation methods. But no need to install nodejs or the package itself, it is a guide that should just highlight one possible reference implementation. - section: Validation in a gateway -> It is not so important to show example AsyncAPI file. More important is to show diagram, the same that was in intro, but with additional component - event gateway (this is something you need to consult with @smoya as I do not remember if this gateway is standalone next to broker or rather a side care to the producer/consumer). And you just explain that the advantage is that validation is delegated to central component. And brought explain on our event gateway example how this could work.
- section: Native broker validation -> here another diagram, showing that validation requests go out from broker to
schema registry. You write that this is common for Kafka broker. In such cases AsyncAPI is not part of the flow, but still plays an important role, because in AsyncAPI document you can still reference the payload schemas stored in the schema registry instead of duplicating them in AsyncAPI document -> example https://github.com/asyncapi/avro-schema-parser#use-them-on-your-asyncapi-document and you can explicitly document where is the schema registry located https://github.com/asyncapi/bindings/tree/master/kafka#server-binding-object
so a bit of refactor is needed
I'm happy to hop on a call if you need me
There was a problem hiding this comment.
hey, yes so is it possible to get on group call with you and @smoya ? I have questions related to studio and event gateway too plus I need some help with code snippets here.
There was a problem hiding this comment.
hey, yes so is it possible to get on group call with you and @smoya ? I have questions related to studio and event gateway too plus I need some help with code snippets here.
Just for the record, this happened today.
Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>
|
@alequetzalli I left some final comments yesterday, please have a look |
Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>
Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>
Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>
Co-authored-by: Akshat Nema <76521428+akshatnema@users.noreply.github.com>
|
/rtm |
Description
Related issue(s)
Fixes #994