From 7c6b514d6eb52d39b1f292ae4255890d357fdddb Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Sep 2023 21:35:23 +0530 Subject: [PATCH 01/25] document adding-operations --- .../concepts/asyncapi-document/_section.md | 4 + .../asyncapi-document/adding-operations.md | 113 ++++++++++++++++++ 2 files changed, 117 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/adding-operations.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md new file mode 100644 index 000000000000..d7dea824ae21 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -0,0 +1,4 @@ +--- +title: 'AsyncAPI Document' +weight: 50 +--- \ No newline at end of file diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md new file mode 100644 index 000000000000..02d13dbc2cac --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -0,0 +1,113 @@ +--- +title: Adding Operations +weight: 60 +--- + +In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. + +## Operations Features + +- Operations describe the behaviors and capabilities of the messaging channels described in the document. + +- In a messaging channel, an operation represents a particular action or interaction that can be performed. + +- The purpose of these operations is to provide a standardized means for describing the process of publishing, subscribing to, requesting, or replying to messages within the messaging system. + +## Steps to Add Operations + +For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. The step-by-step guide on how to add operations to an AsyncAPI document is as follows - + +- Open your AsyncAPI document in a text editor or an AsyncAPI editor tool. + +- Locate the `channels` section in your AsyncAPI document. This section defines the messaging channels and their associated operations. + +- Within the `channels` section, add a new channel using the desired channel name. Channels are represented as properties within the `channels` object, and their names are usually formatted as paths or topics, depending on the messaging protocol you are using (e.g. `/users/{userId}/notifications` or `user.notifications`). + +- Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and request. + +- For each operation, define its details using the appropriate keywords and properties. These details include the operation type, payload schema, headers, bindings, and other relevant information. + +```mermaid +flowchart TD +style A fill:#E5EE8C,stroke:#333,stroke-width:2px +style B fill:#F3A06A,stroke:#333,stroke-width:2px +style C fill:#CBF399,stroke:#333,stroke-width:2px +style D fill:#F5B5EF,stroke:#333,stroke-width:2px +style E fill:#F568A8,stroke:#333,stroke-width:2px + A(Open AsyncAPI document) --> B(Locate the `channels` section) + B --> C(Add a new channel) + C --> D(Specify operations) + D --> E(Define operation details) + classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H,I,J labelStyle; +``` + +## Operations Types + +The operations of the AsyncAPI document are divided into the following different categories based on the purpose they serve - + +- Publishing: In the publish operation, components are able to send messages to specific channels. This operation allows publishers to publish messages or events for consumption by other components. + +```mermaid +flowchart TD +style A fill:#E5EE8C,stroke:#333,stroke-width:2px +style B fill:#CBF399,stroke:#333,stroke-width:2px +style C fill:#F5B5EF,stroke:#333,stroke-width:2px +style D fill:#F568A8,stroke:#333,stroke-width:2px + A[Components] -- Send messages --> B(Publish Operation) + B -- Messages/Events --> C[Specific Channels] + C --> D[Consumption by Other Components] + classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H,I,J labelStyle; +``` + +- Subscribing: By using the subscribe operation, components are able to receive messages from a particular channel. The subscriber can use this operation to indicate whether they are interested in receiving messages from a particular channel. + +```mermaid +flowchart TD +style A fill:#E5EE8C,stroke:#333,stroke-width:2px +style B fill:#CBF399,stroke:#333,stroke-width:2px +style C fill:#F5B5EF,stroke:#333,stroke-width:2px +style D fill:#F568A8,stroke:#333,stroke-width:2px + A[Particular Channels] -- Messages --> B(Subscribe Operation) + B --> D[Indicate Interest in Receiving] + D -- Receive messages--> C[Components] +classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H,I,J labelStyle; +``` + +- Request-Reply: RequestReply establishes a pattern of request-response communication between components. The client can send a request message, and the server will respond with a corresponding reply message. Typically, this operation is used for synchronous communication in which the client anticipates a response from the server. + +```mermaid +flowchart TD +style A fill:#E5EE8C,stroke:#333,stroke-width:2px +style B fill:#F5B5EF,stroke:#333,stroke-width:2px + A[Client] -- Request message --> B(Server) + B -- Reply message --> A +classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H,I,J labelStyle; +``` + +- Request: A request operation allows components to submit a request message without requiring a response from the server. This is typically used in situations where the client does not need a direct response from the server, such as fire-and-forget or one-way communication. + +```mermaid +flowchart TD +style A fill:#CBF399,stroke:#333,stroke-width:2px +style B fill:#F568A8,stroke:#333,stroke-width:2px + A[Client] -- Request message --> B[Server] +classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H,I,J labelStyle; +``` + +- Publish-Subscribe: With the publishSubscribe operation, messages published to a channel are distributed to multiple subscribers in a publish-subscribe pattern. Messages can be broadcast to a number of consumers interested in a particular topic or event at the same time. + +```mermaid +flowchart TD +style A fill:#FFD700,stroke:#333,stroke-width:2px +style B fill:#F3A06A,stroke:#333,stroke-width:2px +style C fill:#3386FF,stroke:#333,stroke-width:2px + A(Publisher) -- Publish messages --> B[Channel] + B -- Messages --> C[Subscribers] + classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H,I,J labelStyle; +``` \ No newline at end of file From 4fff5f311c5514e797b05558fb2256ce613b6a45 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:50:41 +0530 Subject: [PATCH 02/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 02d13dbc2cac..d850d13438c8 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -76,7 +76,7 @@ classDef labelStyle color:#000000; class A,B,C,D,E,F,G,H,I,J labelStyle; ``` -- Request-Reply: RequestReply establishes a pattern of request-response communication between components. The client can send a request message, and the server will respond with a corresponding reply message. Typically, this operation is used for synchronous communication in which the client anticipates a response from the server. +- Request-Reply: Request/Reply establishes a pattern of request-response communication between components. The client can send a request message, and the server will respond with a corresponding reply message. Typically, this operation is used for synchronous communication in which the client anticipates a response from the server. ```mermaid flowchart TD From d361b7f3dbdf58fb58d1544fef6cc44d56c441f6 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:50:49 +0530 Subject: [PATCH 03/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index d850d13438c8..510b0f34497b 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -44,7 +44,7 @@ style E fill:#F568A8,stroke:#333,stroke-width:2px ## Operations Types -The operations of the AsyncAPI document are divided into the following different categories based on the purpose they serve - +The operations of the AsyncAPI document are divided into the following categories based on the purpose they serve - - Publishing: In the publish operation, components are able to send messages to specific channels. This operation allows publishers to publish messages or events for consumption by other components. From 46f9487efb36ff2f743da5636814a88beb155317 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:51:03 +0530 Subject: [PATCH 04/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 510b0f34497b..3f61035f3089 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -42,7 +42,7 @@ style E fill:#F568A8,stroke:#333,stroke-width:2px class A,B,C,D,E,F,G,H,I,J labelStyle; ``` -## Operations Types +## Types The operations of the AsyncAPI document are divided into the following categories based on the purpose they serve - From c59b9fd065546e7f20e31f60b190e5a204e70c5b Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:51:13 +0530 Subject: [PATCH 05/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 3f61035f3089..026985072ee8 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -25,7 +25,7 @@ For adding operations to an AsyncAPI document, we need to define them within the - Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and request. -- For each operation, define its details using the appropriate keywords and properties. These details include the operation type, payload schema, headers, bindings, and other relevant information. +- For each operation, define its details using the appropriate keywords and properties. These details typically include the operation type, payload schema, headers, bindings, and other relevant information. ```mermaid flowchart TD From 26e0044c2b35756d7b64ae679813e149ba189605 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:51:23 +0530 Subject: [PATCH 06/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 026985072ee8..d9e52ba945fa 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -23,7 +23,7 @@ For adding operations to an AsyncAPI document, we need to define them within the - Within the `channels` section, add a new channel using the desired channel name. Channels are represented as properties within the `channels` object, and their names are usually formatted as paths or topics, depending on the messaging protocol you are using (e.g. `/users/{userId}/notifications` or `user.notifications`). -- Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and request. +- Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and `request`. - For each operation, define its details using the appropriate keywords and properties. These details typically include the operation type, payload schema, headers, bindings, and other relevant information. From e5d0e606ebe1a2f54084ff915b38c4bb85a489b4 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:51:43 +0530 Subject: [PATCH 07/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index d9e52ba945fa..96b63c30c454 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -19,7 +19,7 @@ For adding operations to an AsyncAPI document, we need to define them within the - Open your AsyncAPI document in a text editor or an AsyncAPI editor tool. -- Locate the `channels` section in your AsyncAPI document. This section defines the messaging channels and their associated operations. +- Locate the `channels` section in your AsyncAPI document. The `channels` section defines the messaging channels and their associated operations. - Within the `channels` section, add a new channel using the desired channel name. Channels are represented as properties within the `channels` object, and their names are usually formatted as paths or topics, depending on the messaging protocol you are using (e.g. `/users/{userId}/notifications` or `user.notifications`). From 7a9903fa2ad2b6db932885688c9fedfc620e361d Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:52:28 +0530 Subject: [PATCH 08/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 96b63c30c454..581334527d4c 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -15,7 +15,7 @@ In a messaging system, the term "operations" refers to the various methods by wh ## Steps to Add Operations -For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. The step-by-step guide on how to add operations to an AsyncAPI document is as follows - +For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. You can add operations to an AsyncAPI document as follows - - Open your AsyncAPI document in a text editor or an AsyncAPI editor tool. From 2ea6b058b8ac2da9065570d5823be45025458d2e Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:52:38 +0530 Subject: [PATCH 09/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 581334527d4c..5834610ebc7c 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -13,7 +13,7 @@ In a messaging system, the term "operations" refers to the various methods by wh - The purpose of these operations is to provide a standardized means for describing the process of publishing, subscribing to, requesting, or replying to messages within the messaging system. -## Steps to Add Operations +## Adding Operations For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. You can add operations to an AsyncAPI document as follows - From f23afda038816592b96bede63d66ca779cb1d4ab Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:52:48 +0530 Subject: [PATCH 10/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 5834610ebc7c..3a2814a946f4 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -5,7 +5,7 @@ weight: 60 In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. -## Operations Features +## Features - Operations describe the behaviors and capabilities of the messaging channels described in the document. From ea076418ab78d66461395ed61bde92c967204bf7 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 3 Oct 2023 10:52:55 +0530 Subject: [PATCH 11/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 3a2814a946f4..fd50405627ad 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -7,7 +7,7 @@ In a messaging system, the term "operations" refers to the various methods by wh ## Features -- Operations describe the behaviors and capabilities of the messaging channels described in the document. +- Operations describe the behaviors and capabilities of the messaging channels described in the AsyncAPI document. - In a messaging channel, an operation represents a particular action or interaction that can be performed. From 551940cacf206a5f52ab55d61da62e61f74689eb Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Mon, 30 Oct 2023 10:38:01 +0530 Subject: [PATCH 12/25] updated the adding operations sub section --- .../asyncapi-document/adding-operations.md | 59 ++++++++++++------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 02d13dbc2cac..d68259c22797 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -15,31 +15,48 @@ In a messaging system, the term "operations" refers to the various methods by wh ## Steps to Add Operations -For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. The step-by-step guide on how to add operations to an AsyncAPI document is as follows - +`operations` are no longer under `channels` in AsyncAPI Spec 3.0.0, instead, `operations` are separate objects in the AsyncAPI document on the same level. +`channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - -- Open your AsyncAPI document in a text editor or an AsyncAPI editor tool. - -- Locate the `channels` section in your AsyncAPI document. This section defines the messaging channels and their associated operations. - -- Within the `channels` section, add a new channel using the desired channel name. Channels are represented as properties within the `channels` object, and their names are usually formatted as paths or topics, depending on the messaging protocol you are using (e.g. `/users/{userId}/notifications` or `user.notifications`). +``` +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' +``` -- Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and request. +Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for it's definition - -- For each operation, define its details using the appropriate keywords and properties. These details include the operation type, payload schema, headers, bindings, and other relevant information. +| Field Name | Type | Description | +|---|---|---| +| title | string | An easy to understand headline about the operation | +| summary | string | A brief overview of the purpose of the operation | +| description | string | A detailed explanation of the operation | +| Channel | Reference Object Link | A `ref` pointer to the definition of the channel in which the operation is performed | +| Action | "send" or "receive" | Uses `send` when the application sends a message to the given channel, and uses `receive` when the application receives a message from the given channel | +| Tags | Tag Object | List of tags for logical grouping and categorization of operations | +| Bindings | Bindings Object | A map where keys store the name of protocol and the values store protocol-specific definitions for the operation | +| Traits | Traits Object | A list of traits to apply to the operation object. Traits must be merged using Traits Merge Mechanism. The resulting object should be a valid Operation Object | -```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#F3A06A,stroke:#333,stroke-width:2px -style C fill:#CBF399,stroke:#333,stroke-width:2px -style D fill:#F5B5EF,stroke:#333,stroke-width:2px -style E fill:#F568A8,stroke:#333,stroke-width:2px - A(Open AsyncAPI document) --> B(Locate the `channels` section) - B --> C(Add a new channel) - C --> D(Specify operations) - D --> E(Define operation details) - classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; +``` +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' ``` ## Operations Types From b3643a8cfd03f5a8401cc942a0179e7d7ea063d9 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Mon, 30 Oct 2023 10:47:06 +0530 Subject: [PATCH 13/25] removed unwanted characters --- .../asyncapi-document/adding-operations.md | 28 +------------------ 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 030faa9a8c07..ed598b33330c 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -15,12 +15,9 @@ In a messaging system, the term "operations" refers to the various methods by wh ## Adding Operations -<<<<<<< HEAD `operations` are no longer under `channels` in AsyncAPI Spec 3.0.0, instead, `operations` are separate objects in the AsyncAPI document on the same level. `channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - -======= For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. You can add operations to an AsyncAPI document as follows - ->>>>>>> ea076418ab78d66461395ed61bde92c967204bf7 ``` onUserSignUp: @@ -31,11 +28,8 @@ onUserSignUp: $ref: '#/channels/userSignup' ``` -<<<<<<< HEAD Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for it's definition - -======= - Locate the `channels` section in your AsyncAPI document. The `channels` section defines the messaging channels and their associated operations. ->>>>>>> ea076418ab78d66461395ed61bde92c967204bf7 | Field Name | Type | Description | |---|---|---| @@ -48,7 +42,6 @@ Operations can be defined as an independent object in the AsyncAPI document. Ope | Bindings | Bindings Object | A map where keys store the name of protocol and the values store protocol-specific definitions for the operation | | Traits | Traits Object | A list of traits to apply to the operation object. Traits must be merged using Traits Merge Mechanism. The resulting object should be a valid Operation Object | -<<<<<<< HEAD ``` onUserSignUp: title: User sign up @@ -66,25 +59,6 @@ onUserSignUp: ack: false traits: - $ref: '#/components/operationTraits/kafka' -======= -- Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and `request`. - -- For each operation, define its details using the appropriate keywords and properties. These details typically include the operation type, payload schema, headers, bindings, and other relevant information. - -```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#F3A06A,stroke:#333,stroke-width:2px -style C fill:#CBF399,stroke:#333,stroke-width:2px -style D fill:#F5B5EF,stroke:#333,stroke-width:2px -style E fill:#F568A8,stroke:#333,stroke-width:2px - A(Open AsyncAPI document) --> B(Locate the `channels` section) - B --> C(Add a new channel) - C --> D(Specify operations) - D --> E(Define operation details) - classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; ->>>>>>> ea076418ab78d66461395ed61bde92c967204bf7 ``` ## Types @@ -155,4 +129,4 @@ style C fill:#3386FF,stroke:#333,stroke-width:2px B -- Messages --> C[Subscribers] classDef labelStyle color:#000000; class A,B,C,D,E,F,G,H,I,J labelStyle; -``` \ No newline at end of file +``` From 5b4767ef3d49b78b7b56d029b7d8b12151dd2db4 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Mon, 30 Oct 2023 20:45:23 +0530 Subject: [PATCH 14/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Lukasz Gornicki --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index ed598b33330c..0a7325ab1470 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -15,7 +15,7 @@ In a messaging system, the term "operations" refers to the various methods by wh ## Adding Operations -`operations` are no longer under `channels` in AsyncAPI Spec 3.0.0, instead, `operations` are separate objects in the AsyncAPI document on the same level. +`operations` are separate objects in the AsyncAPI document on the same level. `channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. You can add operations to an AsyncAPI document as follows - From 8ab1445c7ddd053fad3b6147d10b2048cbbd80cf Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Mon, 30 Oct 2023 20:45:33 +0530 Subject: [PATCH 15/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Lukasz Gornicki --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 0a7325ab1470..c387f1e1b388 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -11,7 +11,7 @@ In a messaging system, the term "operations" refers to the various methods by wh - In a messaging channel, an operation represents a particular action or interaction that can be performed. -- The purpose of these operations is to provide a standardized means for describing the process of publishing, subscribing to, requesting, or replying to messages within the messaging system. +- The purpose of these operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. ## Adding Operations From dc93f5a7f791ea833dfc39ed22f8659ee9bdb7c0 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Mon, 30 Oct 2023 21:13:32 +0530 Subject: [PATCH 16/25] updated the changes including diagrams, and addition of content --- .../asyncapi-document/adding-operations.md | 92 +++++++------------ 1 file changed, 31 insertions(+), 61 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 030faa9a8c07..fb51896d3ec7 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -13,80 +13,50 @@ In a messaging system, the term "operations" refers to the various methods by wh - The purpose of these operations is to provide a standardized means for describing the process of publishing, subscribing to, requesting, or replying to messages within the messaging system. +## Defining Operations + +Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for it's definition. More information about each field names that are used to define operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). +Additionally, an example to show the usage of each field names in defining operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationsObject). + +The following diagram briefs the important field names that are frequently used to define AsyncAPI operations in Spec 3.0.0 - + +flowchart TD +style A fill:#E5EE8C,stroke:#333,stroke-width:2px +style B fill:#CBF399,stroke:#333,stroke-width:2px +style C fill:#F5B5EF,stroke:#333,stroke-width:2px +style D fill:#F568A8,stroke:#333,stroke-width:2px + +style E fill:#B40486,stroke:#333,stroke-width:2px +style F fill:#86B404,stroke:#333,stroke-width:2px +style G fill:#01A9DB,stroke:#333,stroke-width:2px +style H fill:#F781F3,stroke:#333,stroke-width:2px + + A[Fields required to define AsyncAPI Operations] -->|1| B[Summary] + A -->|2| C[Description] + A -->|3| D[Channel] + A -->|4| E[Action] + A -->|5| F[Tags] + A -->|6| G[Bindings] + A -->|7| H[Traits] + +classDef labelStyle color:#000000; + class A,B,C,D,E,F,G,H labelStyle; + ## Adding Operations -<<<<<<< HEAD `operations` are no longer under `channels` in AsyncAPI Spec 3.0.0, instead, `operations` are separate objects in the AsyncAPI document on the same level. -`channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - -======= -For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. You can add operations to an AsyncAPI document as follows - ->>>>>>> ea076418ab78d66461395ed61bde92c967204bf7 +`channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - ``` onUserSignUp: title: User sign up summary: Action to sign a user up. description: A longer description + action: send channel: $ref: '#/channels/userSignup' ``` -<<<<<<< HEAD -Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for it's definition - -======= -- Locate the `channels` section in your AsyncAPI document. The `channels` section defines the messaging channels and their associated operations. ->>>>>>> ea076418ab78d66461395ed61bde92c967204bf7 - -| Field Name | Type | Description | -|---|---|---| -| title | string | An easy to understand headline about the operation | -| summary | string | A brief overview of the purpose of the operation | -| description | string | A detailed explanation of the operation | -| Channel | Reference Object Link | A `ref` pointer to the definition of the channel in which the operation is performed | -| Action | "send" or "receive" | Uses `send` when the application sends a message to the given channel, and uses `receive` when the application receives a message from the given channel | -| Tags | Tag Object | List of tags for logical grouping and categorization of operations | -| Bindings | Bindings Object | A map where keys store the name of protocol and the values store protocol-specific definitions for the operation | -| Traits | Traits Object | A list of traits to apply to the operation object. Traits must be merged using Traits Merge Mechanism. The resulting object should be a valid Operation Object | - -<<<<<<< HEAD -``` -onUserSignUp: - title: User sign up - summary: Action to sign a user up. - description: A longer description - channel: - $ref: '#/channels/userSignup' - action: send - tags: - - name: user - - name: signup - - name: register - bindings: - amqp: - ack: false - traits: - - $ref: '#/components/operationTraits/kafka' -======= -- Inside the channel definition, specify the desired operations by creating sub-properties for each operation. Common operations include `publish`, `subscribe`, `publishSubscribe`, `requestReply`, and `request`. - -- For each operation, define its details using the appropriate keywords and properties. These details typically include the operation type, payload schema, headers, bindings, and other relevant information. - -```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#F3A06A,stroke:#333,stroke-width:2px -style C fill:#CBF399,stroke:#333,stroke-width:2px -style D fill:#F5B5EF,stroke:#333,stroke-width:2px -style E fill:#F568A8,stroke:#333,stroke-width:2px - A(Open AsyncAPI document) --> B(Locate the `channels` section) - B --> C(Add a new channel) - C --> D(Specify operations) - D --> E(Define operation details) - classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; ->>>>>>> ea076418ab78d66461395ed61bde92c967204bf7 -``` - ## Types The operations of the AsyncAPI document are divided into the following categories based on the purpose they serve - From 9e7a6028de29f2aea3c3c51da4842f98edc90359 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Mon, 30 Oct 2023 21:24:45 +0530 Subject: [PATCH 17/25] updated changes --- .../asyncapi-document/adding-operations.md | 97 +------------------ 1 file changed, 2 insertions(+), 95 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index d2e84bb40743..6724c56a2dc6 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -23,6 +23,7 @@ For adding operations to an AsyncAPI document, we need to define them within the The following diagram briefs the important field names that are frequently used to define AsyncAPI operations in Spec 3.0.0 - +```mermaid flowchart TD style A fill:#E5EE8C,stroke:#333,stroke-width:2px style B fill:#CBF399,stroke:#333,stroke-width:2px @@ -44,24 +45,12 @@ style H fill:#F781F3,stroke:#333,stroke-width:2px classDef labelStyle color:#000000; class A,B,C,D,E,F,G,H labelStyle; +``` ## Adding Operations `operations` are no longer under `channels` in AsyncAPI Spec 3.0.0, instead, `operations` are separate objects in the AsyncAPI document on the same level. `channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - -Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for it's definition - -- Locate the `channels` section in your AsyncAPI document. The `channels` section defines the messaging channels and their associated operations. - -| Field Name | Type | Description | -|---|---|---| -| title | string | An easy to understand headline about the operation | -| summary | string | A brief overview of the purpose of the operation | -| description | string | A detailed explanation of the operation | -| Channel | Reference Object Link | A `ref` pointer to the definition of the channel in which the operation is performed | -| Action | "send" or "receive" | Uses `send` when the application sends a message to the given channel, and uses `receive` when the application receives a message from the given channel | -| Tags | Tag Object | List of tags for logical grouping and categorization of operations | -| Bindings | Bindings Object | A map where keys store the name of protocol and the values store protocol-specific definitions for the operation | -| Traits | Traits Object | A list of traits to apply to the operation object. Traits must be merged using Traits Merge Mechanism. The resulting object should be a valid Operation Object | ``` onUserSignUp: @@ -71,86 +60,4 @@ onUserSignUp: action: send channel: $ref: '#/channels/userSignup' - channel: - $ref: '#/channels/userSignup' - action: send - tags: - - name: user - - name: signup - - name: register - bindings: - amqp: - ack: false - traits: - - $ref: '#/components/operationTraits/kafka' -``` - -## Types - -The operations of the AsyncAPI document are divided into the following categories based on the purpose they serve - - -- Publishing: In the publish operation, components are able to send messages to specific channels. This operation allows publishers to publish messages or events for consumption by other components. - -```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#CBF399,stroke:#333,stroke-width:2px -style C fill:#F5B5EF,stroke:#333,stroke-width:2px -style D fill:#F568A8,stroke:#333,stroke-width:2px - A[Components] -- Send messages --> B(Publish Operation) - B -- Messages/Events --> C[Specific Channels] - C --> D[Consumption by Other Components] - classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; -``` - -- Subscribing: By using the subscribe operation, components are able to receive messages from a particular channel. The subscriber can use this operation to indicate whether they are interested in receiving messages from a particular channel. - -```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#CBF399,stroke:#333,stroke-width:2px -style C fill:#F5B5EF,stroke:#333,stroke-width:2px -style D fill:#F568A8,stroke:#333,stroke-width:2px - A[Particular Channels] -- Messages --> B(Subscribe Operation) - B --> D[Indicate Interest in Receiving] - D -- Receive messages--> C[Components] -classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; -``` - -- Request-Reply: Request/Reply establishes a pattern of request-response communication between components. The client can send a request message, and the server will respond with a corresponding reply message. Typically, this operation is used for synchronous communication in which the client anticipates a response from the server. - -```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#F5B5EF,stroke:#333,stroke-width:2px - A[Client] -- Request message --> B(Server) - B -- Reply message --> A -classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; -``` - -- Request: A request operation allows components to submit a request message without requiring a response from the server. This is typically used in situations where the client does not need a direct response from the server, such as fire-and-forget or one-way communication. - -```mermaid -flowchart TD -style A fill:#CBF399,stroke:#333,stroke-width:2px -style B fill:#F568A8,stroke:#333,stroke-width:2px - A[Client] -- Request message --> B[Server] -classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; -``` - -- Publish-Subscribe: With the publishSubscribe operation, messages published to a channel are distributed to multiple subscribers in a publish-subscribe pattern. Messages can be broadcast to a number of consumers interested in a particular topic or event at the same time. - -```mermaid -flowchart TD -style A fill:#FFD700,stroke:#333,stroke-width:2px -style B fill:#F3A06A,stroke:#333,stroke-width:2px -style C fill:#3386FF,stroke:#333,stroke-width:2px - A(Publisher) -- Publish messages --> B[Channel] - B -- Messages --> C[Subscribers] - classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I,J labelStyle; ``` From aaf499f2a75ad20abc100341608e59950f76feb5 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 31 Oct 2023 11:00:17 +0530 Subject: [PATCH 18/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Lukasz Gornicki --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 6724c56a2dc6..6015568fd48e 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -49,7 +49,7 @@ classDef labelStyle color:#000000; ## Adding Operations -`operations` are no longer under `channels` in AsyncAPI Spec 3.0.0, instead, `operations` are separate objects in the AsyncAPI document on the same level. +`operations` are separate objects in the AsyncAPI document on the root level together with `channels` and other objects. `channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - ``` From 61679a6ef5503ccc784e79659ad09858771e0c23 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 31 Oct 2023 11:00:36 +0530 Subject: [PATCH 19/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Lukasz Gornicki --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 6015568fd48e..c111a82440a2 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -50,7 +50,7 @@ classDef labelStyle color:#000000; ## Adding Operations `operations` are separate objects in the AsyncAPI document on the root level together with `channels` and other objects. -`channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - +Operation must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example: ``` onUserSignUp: From c0da456d473bce3b536724e91762014146c2db2c Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 31 Oct 2023 11:12:12 +0530 Subject: [PATCH 20/25] removed duplicate lines this line was supposed to be removed from the old draft but for some reason, it still wasn't removed when I pushed the changes to github. --- .../docs/concepts/asyncapi-document/adding-operations.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index c111a82440a2..8d26b63524e6 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -15,11 +15,8 @@ In a messaging system, the term "operations" refers to the various methods by wh ## Defining Operations -Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for it's definition. More information about each field names that are used to define operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). -Additionally, an example to show the usage of each field names in defining operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationsObject). -`operations` are separate objects in the AsyncAPI document on the same level. -`channels` can be linked within `operations` by referencing them within the `channels`, just like the following example - -For adding operations to an AsyncAPI document, we need to define them within the channels section of the document. You can add operations to an AsyncAPI document as follows - +Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for their definition. More information about each field name that is used to define operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). +Additionally, an example to show the usage of each field name in defining operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationsObject). The following diagram briefs the important field names that are frequently used to define AsyncAPI operations in Spec 3.0.0 - @@ -50,7 +47,7 @@ classDef labelStyle color:#000000; ## Adding Operations `operations` are separate objects in the AsyncAPI document on the root level together with `channels` and other objects. -Operation must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example: +Operations must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example: ``` onUserSignUp: From debd1647ae669c1806de2b9c9cda8e3819c23884 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 31 Oct 2023 13:22:56 +0530 Subject: [PATCH 21/25] aligned mermaid diagram code with other writers --- .../asyncapi-document/adding-operations.md | 48 +++++++++++-------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 8d26b63524e6..4ea4d00d68ae 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -21,27 +21,37 @@ Additionally, an example to show the usage of each field name in defining operat The following diagram briefs the important field names that are frequently used to define AsyncAPI operations in Spec 3.0.0 - ```mermaid -flowchart TD -style A fill:#E5EE8C,stroke:#333,stroke-width:2px -style B fill:#CBF399,stroke:#333,stroke-width:2px -style C fill:#F5B5EF,stroke:#333,stroke-width:2px -style D fill:#F568A8,stroke:#333,stroke-width:2px - -style E fill:#B40486,stroke:#333,stroke-width:2px -style F fill:#86B404,stroke:#333,stroke-width:2px -style G fill:#01A9DB,stroke:#333,stroke-width:2px -style H fill:#F781F3,stroke:#333,stroke-width:2px - - A[Fields required to define AsyncAPI Operations] -->|1| B[Summary] - A -->|2| C[Description] - A -->|3| D[Channel] - A -->|4| E[Action] - A -->|5| F[Tags] - A -->|6| G[Bindings] - A -->|7| H[Traits] +graph LR +A[Required Fields to define AsyncAPI Operations] +B[Summary] +C[Action] +D[Optional Fields to define AsyncAPI Operations] +E[Description] +F[Channel] +G[Tags] +H[Bindings] +I[Traits] + +A -->|1.| B +A -->|2.| C +D --> |1.| E +D --> |2.| F +D --> |3.| G +D --> |4.| H +D --> |5.| I + +style A fill:#E5EE8C,stroke:#000 +style B fill:#DF7401,stroke:#000 +style C fill:#F5B5EF,stroke:#000 +style D fill:#E5EE8C,stroke:#000 +style E fill:#B40486,stroke:#000 +style F fill:#86B404,stroke:#000 +style G fill:#01A9DB,stroke:#000 +style H fill:#F781F3,stroke:#000 +style I fill:#F568A8,stroke:#000 classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H labelStyle; + class A,B,C,D,E,F,G,H,I labelStyle; ``` ## Adding Operations From 8f5f1dabcb2ffdd5496e9177f2473f2c02a6e30c Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Wed, 1 Nov 2023 18:01:13 +0530 Subject: [PATCH 22/25] updated mermaid diagram to align with the style guide --- .../asyncapi-document/adding-operations.md | 32 +++++++------------ 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 4ea4d00d68ae..f38dd40e8593 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -22,36 +22,26 @@ The following diagram briefs the important field names that are frequently used ```mermaid graph LR -A[Required Fields to define AsyncAPI Operations] +A[Required Fields] B[Summary] C[Action] -D[Optional Fields to define AsyncAPI Operations] +D[Optional Fields] E[Description] F[Channel] G[Tags] H[Bindings] I[Traits] -A -->|1.| B -A -->|2.| C -D --> |1.| E -D --> |2.| F -D --> |3.| G -D --> |4.| H -D --> |5.| I +A --> B +A --> C +D --> E +D --> F +D --> G +D --> H +D --> I -style A fill:#E5EE8C,stroke:#000 -style B fill:#DF7401,stroke:#000 -style C fill:#F5B5EF,stroke:#000 -style D fill:#E5EE8C,stroke:#000 -style E fill:#B40486,stroke:#000 -style F fill:#86B404,stroke:#000 -style G fill:#01A9DB,stroke:#000 -style H fill:#F781F3,stroke:#000 -style I fill:#F568A8,stroke:#000 - -classDef labelStyle color:#000000; - class A,B,C,D,E,F,G,H,I labelStyle; +style A fill:#47BCEE,stroke:#000; +style D fill:#47BCEE,stroke:#000 ``` ## Adding Operations From af6fa6c0ab0ddef88b4ef771eee5e532bca4be07 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Wed, 1 Nov 2023 19:00:23 +0530 Subject: [PATCH 23/25] added field name details in operations --- .../asyncapi-document/adding-operations.md | 75 ++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index f38dd40e8593..48a1963592c8 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -3,7 +3,7 @@ title: Adding Operations weight: 60 --- -In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. +In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. Operations are useful for understanding how the messaging system in AsyncAPI works, and how different components within the system communicate with each other asynchronously. They help developers and users to understand the tasks that API can perform. ## Features @@ -58,3 +58,76 @@ onUserSignUp: channel: $ref: '#/channels/userSignup' ``` + +## Field Names in Operations + +### Summary: + +This section has a short summary of what the operation is about + +``` +"summary": "Action to sign a user up.", +``` + +### Actions: + +Uses the value `send` when the application sends a message to a given channel and uses the value `receive` when the application receives a message from a given channel. + +``` +"action": "receive", +``` + +### Description + +A detailed explanation of the operation. + +``` +"description": "A longer description" +``` + +### Channel + +A `$ref` link is added to link the channels. + +``` +"channel": { + "$ref": "#/channels/userSignup" + } +``` + +### Tags + +A list of tags are used for logical grouping and categorization of operations + +``` +"tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ] +``` + +### Bindings + +A map that stores names of protocols as keys, and protocol-specific definitions as values. + +``` +"bindings": { + "amqp": { + "ack": false + } + } +``` + +### Traits + +A list of traits is added to Operations, which are merged into operations using `JSON Merge Patch`. + +``` +"traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] +``` + + + From 511e89a75c16b55bf7cd9b17eaffc0bb62937bc9 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 7 Nov 2023 19:13:17 +0530 Subject: [PATCH 24/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- .../docs/concepts/asyncapi-document/adding-operations.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 48a1963592c8..9ddd6fc68d83 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -5,13 +5,7 @@ weight: 60 In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. Operations are useful for understanding how the messaging system in AsyncAPI works, and how different components within the system communicate with each other asynchronously. They help developers and users to understand the tasks that API can perform. -## Features - -- Operations describe the behaviors and capabilities of the messaging channels described in the AsyncAPI document. - -- In a messaging channel, an operation represents a particular action or interaction that can be performed. - -- The purpose of these operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. +In a AsyncAPI document, Operations describe the behaviors and capabilities of the messaging channels described in the AsyncAPI document. In a messaging channel, an `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. ## Defining Operations From 436b618f7bac98dc197316aa10903e2c4470e112 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 7 Nov 2023 19:13:43 +0530 Subject: [PATCH 25/25] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 9ddd6fc68d83..625c06f5aa49 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -12,7 +12,7 @@ In a AsyncAPI document, Operations describe the behaviors and capabilities of th Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for their definition. More information about each field name that is used to define operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). Additionally, an example to show the usage of each field name in defining operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationsObject). -The following diagram briefs the important field names that are frequently used to define AsyncAPI operations in Spec 3.0.0 - +The following diagram briefs the some field names that are frequently used to define operations in a AsyncAPI document: ```mermaid graph LR