docs: adding document for adding messages

pages/docs/concepts/asyncapi-document/adding-messages.md

@@ -0,0 +1,156 @@
+---
+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.
+
+## 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.
+
+
+Here is a diagram showing some channel fields and the relation between channel messages and components messages:
+
+```mermaid
+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;
+```
+
+### Channels section
+
+Define the channels section in your AsyncAPI document, including the `messages` your channel accepts. For example:
+
+```yaml
+channels:
+  allCommentLiked:
+    address: comment/liked
+    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
+    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`.
+
+### `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:
+
+```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
+```
+
+You can reuse messages using the [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) like in the following example:
+
+```yml
+    messages:
+      commentLiked:
+        $ref: '#/components/messages/commentLiked'
+```
+
+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
+```
+
+### 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`.
+
+```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.
+```
+
+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`.
+
+### 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.
+
+```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'
+```
+
+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`.