-
-
Notifications
You must be signed in to change notification settings - Fork 577
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: new guide for message validation #1005
Conversation
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site settings. |
|
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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-validator
comes 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
tiny suggestions left
@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>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
superb work!!!
Co-authored-by: Akshat Nema <76521428+akshatnema@users.noreply.github.com>
/rtm |
Description
Related issue(s)
Fixes #994