docs: introduce AsyncAPI document #1868
Conversation
quetzalliwrites
added
📑 docs
area/docs
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
quetzalliwrites
changed the title
Oops 🙊 |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-1868--asyncapi-website.netlify.app/ |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-1868--asyncapi-website.netlify.app/ |
|
Heyooo @derberg/ @smoya / @jonaslagoni ...this document introduces the |
|
The preview link to the doc (https://deploy-preview-1868--asyncapi-website.netlify.app/docs/concepts/asyncapi-document) is giving me a 404. I don't understand (yet) why since I made sure to add the required Feedback is welcome 😂 |
There was a problem hiding this comment.
I love the idea of expanding what the Spec documentation says 🙌 . I really believe we need this kind of documents if we really want to engage more people not only as users but as developers of AsyncAPI.
Thanks for starting this series of documents @alequetzalli!
I did a first review on it and dropped few comments, always assuming this docs will land for v3 and not v2. If that's not correct, please tell me.
Feel free to reach me for any questions.
| version: 0.1.0 | ||
| channels: | ||
| user/signedup: | ||
| subscribe: |
There was a problem hiding this comment.
This is actually an invalid document. Version 3 changed how channels, operations, and messages are described and linked.
It also changed the terms Publish/Subscribe to Receive/Send in that order, since documents changed from being Client-Centric to Application-Centric (meaning they describe the applications API and not the client's interaction within those APIs).
Ok, probably too much info there to digest 😓 .
Let's start with some of the changes in v3 that affect this example:
Publish/Subscribething. Here is a simple cheat sheet I made for the talk I presented at the EDA Summit 23 that helps to convert from v2 to v3.- Channels now have a new field called
addressthat holds the address of the channel. Now the name of the channel can be whatever name. I recommenduserSignedUphere. - Channels don't include the Operation anymore. Instead, Operations are defined in the root document and are "linked" to the channel.
Applying all the previous, your document will look like this:
asyncapi: 3.0.0
info:
title: Cool Example
version: 0.1.0
channels:
userSignedUp:
address: user/signedup
messages:
userSignedUp:
description: An event describing that a user just signed up.
payload:
type: object
additionalProperties: false
properties:
fullName:
type: string
email:
type: string
format: email
age:
type: integer
minimum: 18
operations:
userSignedUp:
action: send
channel:
$ref: '#/channels/userSignedUp'There was a problem hiding this comment.
Whoa, this was a lot of info but I really appreciate how fully you described everything. Thank you 🙏 !!!
One thing slightly confuses me... When you wrote changed the terms Publish/Subscribe to Receive/Send in that order, that made complete sense to me. With you so far. But then when I looked at your cheatsheet, my mind feels like it's trying to do gymnastics. Are you saying that in v3:
- applications no longer subscribe, they
send - applications no longer publish, they
receive
?
I have copied your updated code snippet and will integrate in my next commit. ✌🏽
There was a problem hiding this comment.
The reality is that the approach or point of view of the documented API changes. In v3, we now clearly state that:
The AsyncAPI Specification defines a set of files required to describe the API of an application.
Meaning the document describes the API of the application that offers the AsyncAPI document.
That means operations with the action send, means that the application will perform that operation by sending the messages. On the contrary, receive means the application expects to receive those messages.
|
|
||
|
|
||
| <Remember> | ||
| You might have additional fields depending on the implemented protocol (i.e., MQTT, AMQP, Kafka, etc.). |
There was a problem hiding this comment.
I would clarify this with an example
There was a problem hiding this comment.
Thank you, noted. Added an example, you let me know if you like it.
| @@ -0,0 +1,61 @@ | |||
| --- | |||
| title: 'Introduction' | |||
| weight: 1 | |||
There was a problem hiding this comment.
with subsections it works this way that the "starting weight" is the weight of the _section.md so change it to 50 or more and all the next documents should follow. This way you fix preview and make sure it shows in the UI
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-1868--asyncapi-website.netlify.app/ |
Co-authored-by: Sergio Moya <[email protected]>
|
Hey there @smoya (cc @derberg), I have FINALLY sat down and addressed all of your great feedback on my GSoD PR introducing the topic of the AsyncAPI document. If possible, I would truly appreciate a review from you again. 🙏 Lukasz, I definitely need your review and (eventual) stamp of approval on my PR. Appreciate your review 🙏 |
| weight: 50 | ||
| --- | ||
|
|
||
| The AsyncAPI Specification defines a set of files required to describe the API of an application. One of those files is the AsyncAPI document; it describes the message-driven API in accordance with the AsyncAPI Specification via JSON objects that conform to the JSON standards. (YAML, being a superset of JSON, can also be used.) The AsyncAPI document offers a standardized approach for documenting and describing asynchronous and event-driven systems, clearly defining various components like channels and messages. Additionally, users can leverage both the AsyncAPI document and tools like the AsyncAPI Generator for code and documentation generation, enhancing efficiency and consistency in their development processes. |
There was a problem hiding this comment.
One of those files is the AsyncAPI document
I don't think we have other kind of files rather than the AsyncAPI document.
There was a problem hiding this comment.
ah, noted! fixing
Co-authored-by: Sergio Moya <[email protected]>
|
Thank you soooo much, @smoya for another review! I have addressed all your feedback, so this is ready for review again 😄😅 |
| weight: 50 | ||
| --- | ||
|
|
||
| The AsyncAPI Specification defines a set of files (AsyncAPI documents) required to describe the API of an application. The AsyncAPI document describes the message-driven API in accordance with the AsyncAPI Specification via JSON objects that conform to the JSON standards. YAML, being a superset of JSON, can also be used. It also offers a standardized approach for documenting and describing asynchronous and event-driven systems, clearly defining various objects such as channels and messages. Additionally, users can leverage both the AsyncAPI document and tools like the AsyncAPI Generator for code and documentation generation, enhancing efficiency and consistency in their development processes. |
There was a problem hiding this comment.
The AsyncAPI Specification defines a set of files (AsyncAPI documents) required to describe the API of an application. The AsyncAPI document describes the message-driven API
I'm not a fan of this, but I know this is how we have it in spec document 😆 so first we need to fix it there.
it is not that spec defines a set of files. Spec defines a set of fields that one can use to create one or more asyncapi document that describe an API of the app, and such single AsyncAPI document can reference other files that may contain some fields described in he spec
spec says The AsyncAPI Specification defines a set of files required to describe the API of an application - and I think it is a "train of thought" that refers to a fact that one AsyncAPI document can consist of multiple files (because of Reference Object concept, basically refers to this doc) and not that you create a set of AsyncAPI documents for an app. I hope you know what I mean, not sure how explain it better.
super hard to explain with words
in example: you have an AsyncAPI document like https://github.com/asyncapi/spec/blob/master/examples/social-media/backend/asyncapi.yaml but it also contains references to files like https://github.com/asyncapi/spec/blob/master/examples/social-media/common/servers.yaml
☝🏼 is what spec explanation means by The AsyncAPI Specification defines a set of files required to describe the API of an application because in the end it is not just one AsyncAPI document but also another files with some shared fields
when you write The AsyncAPI Specification defines a set of files (AsyncAPI documents), especially the part (AsyncAPI documents) kinda suggests that one app always has set of AsyncAPI documents, but there is always one
please write you know what I mean 🙏🏼 😄 as I have a feeling I got into a loop 😅
There was a problem hiding this comment.
Here's what I understand... lemme know if you agree @derberg
The original spec text seems to inaccurately suggest that multiple AsyncAPI documents are required for each application, whereas you're saying that a single AsyncAPI document, potentially referencing other files, is typically used to describe an application's API.
Perhaps it is more accurate to say that the AsyncAPI Specification defines a set of fields that can be used in one or more AsyncAPI documents to describe an application's API. A single AsyncAPI document can reference other files, but it doesn't mean that multiple AsyncAPI documents are required for a single application.
While the AsyncAPI document is the primary file describing the API, it can include references to other files that contain additional details or shared fields. This doesn't equate to requiring multiple AsyncAPI documents for a single application.
📣 How about the following instead?
Proposing the following update to the Spec and this document:
The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an application's API. The document may reference other files for additional details or shared fields, but it is typically a single, primary document that encapsulates the API description.
There was a problem hiding this comment.
Spec PR @derberg: asyncapi/spec#1003
There was a problem hiding this comment.
perfect, thanks a 💯 you can update this PR to and we can merge it
Description
As part of Google Season of Docs 2023 at AsyncAPI, we're going to write in-depth explanations of the different sections of an AsyncAPI document to avoid difficulties in implementing EDAs.
For this document issue, we'll introduce the AsyncAPI document and why it is necessary.
Related issue(s)
This task is part of the GSoD Docs EPIC: #1507.