From 93378d00a3359fbce39d1dad1f4b84cabdecfeb5 Mon Sep 17 00:00:00 2001 From: Mahfuza Humayra Mohona Date: Fri, 8 Dec 2023 16:59:01 +0600 Subject: [PATCH 1/4] add message page --- .../asyncapi-document/adding-messages.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/adding-messages.md diff --git a/pages/docs/concepts/asyncapi-document/adding-messages.md b/pages/docs/concepts/asyncapi-document/adding-messages.md new file mode 100644 index 00000000000..6ec9649eea3 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/adding-messages.md @@ -0,0 +1,136 @@ +--- +title: Adding Messages +weight: 140 +--- + +Adding [messages](../message) in an AsyncAPI document primarily involves defining channels, operations, and messages, which is crucial for documenting the exchange of data between your applications. In AsyncAPI, you define the interaction of your application with a message broker in terms of channels and operations. [Channels](../channel) are the medium through which messages are sent or received, while operations represent the actions of publishing or subscribing to these channels. + +Here is a diagram explaining messages: + +```mermaid +graph TD; + A[AsyncAPI Message] --> B[Headers] + A --> C[Payload] + + style A fill:#47BCEE,stroke:#47BCEE; +``` + +The above diagram shows the components of AsyncAPI messages: headers and payload. + +Here is an example of a simple message: + +```yml +channels: + user/signedup: + address: 'application/json' + messages: + userSignUp: + $ref: '#/components/messages/userSignUp' +``` + +This document defines a `user/signedup` channel where a `userSignUp` message can be made. + +## Using multiple message types + +AsyncAPI supports defining multiple possible message types for a single channel. + +Here is a diagram showing the use of multiple message types: + +```mermaid +graph TD; + A[Operations] --> B[Messages] + B --> C[Message Type 1] + B --> D[Message Type 2] + style B fill:#47BCEE,stroke:#47BCEE; +``` + +This diagram shows how AsyncAPI uses multiple message types for a single channel. + +Here is an example document of how AsyncAPI supports the use of multiple message types for a single channel: + +```yml +channels: + userSignupWithReply: + messages: + signup: + $ref: '#/components/messages/userSignedUp' + reply: + $ref: '#/components/messages/userSignedUpReply' +``` + +The above document shows a channel `userSignupWithReply` under which two messages can be sent or received: `userSignedUp` or `userSignedUpReply`. + +## Specifying `contentType` in messages + +The `contentType` field specifies the format of the payload. If it's not provided, the default payload format is `application/json`. + +Here is a diagram showing how to specify `contentType` in messages: + +```mermaid +graph TD; + A[AsyncAPI Message] --> B[contentType] + style A fill:#47BCEE,stroke:#47BCEE; +``` + +The above diagram shows an AsyncAPI message that can specify a content type (`contentType`), which defaults to `application/json`. + +The following code shows how `contentType` is added to the Message: + +```yml +messageId: userSignup +name: UserSignup +title: User signup +summary: Action to sign a user up. +description: A longer description +contentType: application/json +``` + +In this document, the `contentType` is specified as `application/json` for the `userSignup` message. + +## Reusing components + +The components object in the AsyncAPI specification contains reusable objects, but they will only impact the application if they are specifically referred to outside the components object. + +Here is a diagram explaining how to reuse components: + +```mermaid +flowchart TB + +subgraph Components Object + Component_1 + Component_2 + Component_3 +end + +subgraph API + API_implementation --> Component_1:Uses + API_implementation --> Component_2:Uses + API_implementation --> Component_3:Uses + + style API_implementation fill:#47BCEE,stroke:#47BCEE; +end +``` + +The above diagram shows how components in the API implementation are used by various components, emphasizing their impact when referred to outside the components object. + +Here is an example demonstrating how components are reused in AsyncAPI: + +```yml +components: + messages: + user: + contentType: 'application/json' + schema: + $ref: '#/components/schemas/User' + + schemas: + User: + type: object + properties: + id: + type: string + name: + type: string +``` + +The above document shows reuse of a component by defining a `User` schema. From 23c546c09443416fce3f67af2e52ea15e5b97b95 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 13 Dec 2023 14:52:12 +0100 Subject: [PATCH 2/4] Update adding-messages.md --- .../asyncapi-document/adding-messages.md | 218 ++++++++++-------- 1 file changed, 119 insertions(+), 99 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-messages.md b/pages/docs/concepts/asyncapi-document/adding-messages.md index 6ec9649eea3..2c857a6ca28 100644 --- a/pages/docs/concepts/asyncapi-document/adding-messages.md +++ b/pages/docs/concepts/asyncapi-document/adding-messages.md @@ -3,134 +3,154 @@ title: Adding Messages weight: 140 --- -Adding [messages](../message) in an AsyncAPI document primarily involves defining channels, operations, and messages, which is crucial for documenting the exchange of data between your applications. In AsyncAPI, you define the interaction of your application with a message broker in terms of channels and operations. [Channels](../channel) are the medium through which messages are sent or received, while operations represent the actions of publishing or subscribing to these channels. +Adding [messages](/docs/reference/specification/v3.0.0#messageObject) in an AsyncAPI document primarily involves defining channels and operations which is crucial for documenting the exchange of data between your applications. Although it is possible that you may want to use AsyncAPI document to only describe the messages and nothing else. -Here is a diagram explaining messages: +## Add messages -```mermaid -graph TD; - A[AsyncAPI Message] --> B[Headers] - A --> C[Payload] - - style A fill:#47BCEE,stroke:#47BCEE; -``` - -The above diagram shows the components of AsyncAPI messages: headers and payload. - -Here is an example of a simple message: - -```yml -channels: - user/signedup: - address: 'application/json' - messages: - userSignUp: - $ref: '#/components/messages/userSignUp' -``` +You define messages under channels. Although best practice is first define messages under components as reusable definitions so you can reference them from a channel. -This document defines a `user/signedup` channel where a `userSignUp` message can be made. -## Using multiple message types - -AsyncAPI supports defining multiple possible message types for a single channel. - -Here is a diagram showing the use of multiple message types: +Here is a diagram showing some channel fields and the relation between channel messages and components messages: ```mermaid -graph TD; - A[Operations] --> B[Messages] - B --> C[Message Type 1] - B --> D[Message Type 2] - style B fill:#47BCEE,stroke:#47BCEE; +graph LR + C[channels] + F[title] + I[address] + A[components] + B[messages] + D[messages] + C --> F + C --> I + C --> D + D --> |$ref| B + A --> B + + style C fill:#47BCEE,stroke:#000; + style D fill:#47BCEE,stroke:#000; ``` -This diagram shows how AsyncAPI uses multiple message types for a single channel. +### Channels section -Here is an example document of how AsyncAPI supports the use of multiple message types for a single channel: +Define the channels section in your AsyncAPI document, including the `messages` your channel accepts. For example: -```yml +```yaml channels: - userSignupWithReply: + allCommentLiked: + address: comment/liked messages: - signup: - $ref: '#/components/messages/userSignedUp' - reply: - $ref: '#/components/messages/userSignedUpReply' + commentLiked: + description: Message that is being sent when a comment has been liked by someone. + payload: + type: object + title: commentLikedPayload + additionalProperties: false + properties: + commentId: + type: string + description: Id of the comment that was liked + description: Notification channel for all the services that need to know comment is liked. ``` -The above document shows a channel `userSignupWithReply` under which two messages can be sent or received: `userSignedUp` or `userSignedUpReply`. +Above example presents an application that communicates over `allCommentLiked` channel. This channel that accepts only one message called `commentLiked`. -## Specifying `contentType` in messages +### `messages` section -The `contentType` field specifies the format of the payload. If it's not provided, the default payload format is `application/json`. +Define the `components.messages` section in your AsyncAPI document. For each message relevant to your application, provide reusable message definition so when defininig multiple channels you avoid repeating the message definitions. For example: -Here is a diagram showing how to specify `contentType` in messages: - -```mermaid -graph TD; - A[AsyncAPI Message] --> B[contentType] - style A fill:#47BCEE,stroke:#47BCEE; +```yaml +components: + messages: + commentLiked: + description: Message that is being sent when a comment has been liked by someone. + payload: + type: object + title: commentLikedPayload + additionalProperties: false + properties: + commentId: + type: string + description: Id of the comment that was liked ``` -The above diagram shows an AsyncAPI message that can specify a content type (`contentType`), which defaults to `application/json`. - -The following code shows how `contentType` is added to the Message: +You can reuse messages using the [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) like in the following example: ```yml -messageId: userSignup -name: UserSignup -title: User signup -summary: Action to sign a user up. -description: A longer description -contentType: application/json + messages: + commentLiked: + $ref: '#/components/messages/commentLiked' ``` -In this document, the `contentType` is specified as `application/json` for the `userSignup` message. - -## Reusing components - -The components object in the AsyncAPI specification contains reusable objects, but they will only impact the application if they are specifically referred to outside the components object. - -Here is a diagram explaining how to reuse components: - -```mermaid -flowchart TB +Here's the complete AsyncAPI document with channels reusing the same message: +```yml +asyncapi: 3.0.0 +info: + title: Example API + version: '1.0.0' +channels: + allCommentLiked: + address: comment/liked + messages: + commentLiked: + $ref: '#/components/messages/commentLikedUnliked' + description: Notification channel for all the services that need to know comment is liked. + allCommentUnliked: + address: comment/unliked + messages: + commentUnliked: + $ref: '#/components/messages/commentLikedUnliked' + description: Notification channel for all the services that need to know comment is liked. +components: + messages: + commentLikedUnliked: + description: Message that is being sent when a comment has been liked or unliked by someone. + payload: + type: object + title: commentInfoPayload + additionalProperties: false + properties: + commentId: + type: string + description: Id of the comment that was liked or unliked +``` -subgraph Components Object - Component_1 - Component_2 - Component_3 -end +### Identifier of the message -subgraph API - API_implementation --> Component_1:Uses - API_implementation --> Component_2:Uses - API_implementation --> Component_3:Uses +Name of the key that represents a message in AsyncAPI document must be interpreted as `messageId`. In case your document defines channels, the key of the message defined in the channel is the `messageId`. - style API_implementation fill:#47BCEE,stroke:#47BCEE; -end +```yaml +channels: + allCommentLiked: + address: comment/liked + messages: + commentLiked: + $ref: '#/components/messages/commentLikedUnliked' + description: Notification channel for all the services that need to know comment is liked. ``` -The above diagram shows how components in the API implementation are used by various components, emphasizing their impact when referred to outside the components object. +Above example shows a `commentLiked` message under `allCommentLiked` channel. It references a reusable message definition from the `components` section that is represented by `commentLikedUnliked` key. In this setup `commentLiked` key is the `messageId` and not `commentLikedUnliked`. -Here is an example demonstrating how components are reused in AsyncAPI: +### Messages under operations -```yml -components: - messages: - user: - contentType: 'application/json' - schema: - $ref: '#/components/schemas/User' - - schemas: - User: - type: object - properties: - id: - type: string - name: - type: string +Operations reference what channels the are performed against. If channel definition contains multiple different messages but your operation relates to only one of these, you need to specify under operation what message it uses. + +```yaml +channels: + allComments: + address: comments + messages: + commentLiked: + $ref: '#/components/messages/commentLikedMsg' + commentUnliked: + $ref: '#/components/messages/commentUnlikedMsg' + description: Notification channel for all the services that need to know comment is liked. +operations: + onCommentLiked: + action: receive + channel: + $ref: '#/channels/allComments' + messages: + - $ref: '#/channels/allComments/messages/commentLiked' ``` -The above document shows reuse of a component by defining a `User` schema. +Above example shows how you can specify what message `onCommentLiked` operation will receive from the `allCommentLiked` channel. Notice that the reference information about the message points to the channel, not components section. This way you get a proper information about the `messageId`, which is `commentLiked` and not `commentLikedMsg`. From 4bcd511bfd2c34d273ad99a8f01145885ae8a41a Mon Sep 17 00:00:00 2001 From: Mahfuza Humayra Mohona Date: Fri, 15 Dec 2023 08:04:53 +0600 Subject: [PATCH 3/4] updated alequetzalli 's review --- pages/docs/concepts/asyncapi-document/adding-messages.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-messages.md b/pages/docs/concepts/asyncapi-document/adding-messages.md index 2c857a6ca28..e83b3b6474b 100644 --- a/pages/docs/concepts/asyncapi-document/adding-messages.md +++ b/pages/docs/concepts/asyncapi-document/adding-messages.md @@ -1,14 +1,13 @@ --- -title: Adding Messages +title: Adding messages weight: 140 --- -Adding [messages](/docs/reference/specification/v3.0.0#messageObject) in an AsyncAPI document primarily involves defining channels and operations which is crucial for documenting the exchange of data between your applications. Although it is possible that you may want to use AsyncAPI document to only describe the messages and nothing else. +In an AsyncAPI document, adding [messages](/docs/reference/specification/v3.0.0#messageObject) mainly means setting up channels and operations. This is key for explaining how data moves between your applications. However, sometimes you might just want to use the AsyncAPI document to describe the messages themselves, without anything else. ## Add messages -You define messages under channels. Although best practice is first define messages under components as reusable definitions so you can reference them from a channel. - +In an AsyncAPI document, you define message definitions under channels. However, the best practice is to first define these messages under the 'components' section as reusable definitions. That way, you can reference them easily from a channel. Here is a diagram showing some channel fields and the relation between channel messages and components messages: @@ -52,7 +51,7 @@ channels: description: Notification channel for all the services that need to know comment is liked. ``` -Above example presents an application that communicates over `allCommentLiked` channel. This channel that accepts only one message called `commentLiked`. +The above example presents an application that communicates over the `allCommentLiked` channel, which only accepts one message called `commentLiked`. ### `messages` section From cfddb5b8c157c48e10a0fe23fb60934df54b1ddb Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 15 Dec 2023 08:28:52 -0800 Subject: [PATCH 4/4] tw editorial fixes --- .../asyncapi-document/adding-messages.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-messages.md b/pages/docs/concepts/asyncapi-document/adding-messages.md index e83b3b6474b..9f81a798fdb 100644 --- a/pages/docs/concepts/asyncapi-document/adding-messages.md +++ b/pages/docs/concepts/asyncapi-document/adding-messages.md @@ -35,7 +35,7 @@ Define the channels section in your AsyncAPI document, including the `messages` ```yaml channels: - allCommentLiked: + allCommentsLiked: address: comment/liked messages: commentLiked: @@ -51,11 +51,11 @@ channels: description: Notification channel for all the services that need to know comment is liked. ``` -The above example presents an application that communicates over the `allCommentLiked` channel, which only accepts one message called `commentLiked`. +The above example presents an application that communicates over the `allCommentsLiked` channel, which only accepts one message called `commentLiked`. ### `messages` section -Define the `components.messages` section in your AsyncAPI document. For each message relevant to your application, provide reusable message definition so when defininig multiple channels you avoid repeating the message definitions. For example: +In your AsyncAPI document, create a `components.messages` section to define each message your application uses as a reusable message. When setting up multiple channels, you won't have to repeat the same message definitions. For example: ```yaml components: @@ -72,7 +72,7 @@ components: description: Id of the comment that was liked ``` -You can reuse messages using the [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) like in the following example: +You can reuse messages using the [Reference Object](/docs/reference/specification/v3.0.0#referenceObject). For example: ```yml messages: @@ -87,7 +87,7 @@ info: title: Example API version: '1.0.0' channels: - allCommentLiked: + allCommentsLiked: address: comment/liked messages: commentLiked: @@ -115,11 +115,11 @@ components: ### Identifier of the message -Name of the key that represents a message in AsyncAPI document must be interpreted as `messageId`. In case your document defines channels, the key of the message defined in the channel is the `messageId`. +The key name that represents a message in your AsyncAPI document must be interpreted as `messageId`. If your document defines channels, the message key defined in the channel is the `messageId`. ```yaml channels: - allCommentLiked: + allCommentsLiked: address: comment/liked messages: commentLiked: @@ -127,11 +127,11 @@ channels: description: Notification channel for all the services that need to know comment is liked. ``` -Above example shows a `commentLiked` message under `allCommentLiked` channel. It references a reusable message definition from the `components` section that is represented by `commentLikedUnliked` key. In this setup `commentLiked` key is the `messageId` and not `commentLikedUnliked`. +The above example shows a `commentLiked` message under the `allCommentsLiked` channel. It references a reusable message definition from the `components` section represented by the `commentLikedUnliked` key. In this setup, the `commentLiked` key is the `messageId` and not `commentLikedUnliked`. ### Messages under operations -Operations reference what channels the are performed against. If channel definition contains multiple different messages but your operation relates to only one of these, you need to specify under operation what message it uses. +Operations specify which channels they interact with. If a channel has several messages, but your operation only involves one, indicate which specific message the operation uses. ```yaml channels: @@ -152,4 +152,4 @@ operations: - $ref: '#/channels/allComments/messages/commentLiked' ``` -Above example shows how you can specify what message `onCommentLiked` operation will receive from the `allCommentLiked` channel. Notice that the reference information about the message points to the channel, not components section. This way you get a proper information about the `messageId`, which is `commentLiked` and not `commentLikedMsg`. +The above example demonstrates how to specify the message for the `onCommentsLiked` operation received from the `allCommentLiked` channel. It's important to note that the message reference points to the channel, not the components section. That ensures accurate information about the `messageId`, which in this case is `commentLiked`, not `commentLikedMsg`.