From 8a16fbab9856d45c47323da89a06167a8c074d72 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Sun, 16 Jul 2023 14:11:07 +0530 Subject: [PATCH 01/13] add: Intial draft of `tags` document --- .../concepts/asyncapi-document/_section.md | 4 + pages/docs/concepts/asyncapi-document/tags.md | 249 ++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/tags.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md new file mode 100644 index 00000000000..d7dea824ae2 --- /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/tags.md b/pages/docs/concepts/asyncapi-document/tags.md new file mode 100644 index 00000000000..0d72004d4da --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -0,0 +1,249 @@ +--- +title: 'Tags' +weight: 63 +--- + +--- Unique Description about AsyncAPI document to be inserted here --- + +A `tag` is a label or category that helps you logically group related objects such as channels or servers within an event-driven system. The `tags` object provide a structured way to group channels, operations or other components based on their functionality, purpose and/or any other relevant criteria. + +The `tags` object serves as a container for defining and managing tags in a systematic manner. Within the `tags` object, you can define individual tags, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. + +Once tags are defined within the `tags` object, they can be assigned to channels, operations or any other component using the tags property. By including the relevant tag names in the tags property, objects such as channels, servers or components are associated with the appropriate tags, grouping them together based on their shared characteristics. + +Additionally, `tags` can also be included in the [`components` object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#componentsObject) of a AsyncAPI document, which enables the reusuability of the tags. `tags` included in the `components` object can re-used by [reference objects](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). + +## `Tags` in AsyncAPI Document +The `tags` object is a list of `tag` objects which can be referenced by [reference object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). + +The `tags` object within the AsyncAPI specification contains some fields that define and describe individual tags. + +The behavior and impact of the `tags` object within the AsyncAPI document can vary depending on the context of the object in which it is being used. For instance, The way `tags` object impacts a server object is different from when it is used under the channels object. + +Some of the fields that `tags` object holds are: +- `name`: The name of the tag. +- `description`: A short description for the tag. +- `externalDocs`: Additional external documentation for this tag. + +### `Tags` in `Info` Object +Tags when defined within the `tags` property of the `info` object provides a high-level categorization and classification for the entire AsyncAPI document. These tags that are defined under the `info` object give a global context to the entire application, representing overarching themes or functional areas within the event-driven system. They serve as a way to group objects such as channels or servers based on their broader significance, providing a holistic understanding of the application's structure. + +Here's a visual representation of `tags` object inside a `info` object in a AsyncAPI document: +```mermaid +graph LR + A[asyncapi] --> B[info] + B --> C[title] + B --> D[version] + B --> E[description] + B --> F[tags] + F --> G[name] + F --> I[description] + F --> K[externalDocs] +``` + +Below is a example of the `tags` object inside the `info` object in a AsyncAPI document: +```yaml +asyncapi: 3.0.0 +info: + title: AsyncAPI Documentation + version: 1.0.0 + description: | + This AsyncAPI document provides a overview + of the event-driven system. + tags: + - name: Finance + description: APIs related to financial transactions + - name: Customer + description: APIs related to customer interactions + - name: Inventory + description: APIs related to inventory management +``` + +### `Tags` in `Servers` Object +Tags when used within the `tags` property of the `servers` object, they are specific to the servers configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using tags in servers object allows for the categorization and organization of servers based on specific tags or labels. + +Here's a visual representation of `tags` object inside a `servers` object in a AsyncAPI document: +```mermaid +graph LR + A[asyncapi] --> B[servers] + B --> C[host] + B --> D[description] + B --> E[protocol] + B --> F[protocolVersion] + B --> G[tags] + G --> H[name] + G --> I[description] + G --> J[externalDocs] +``` + +Below is a example of the `tags` object inside the `servers` object in a AsyncAPI document: +```yaml +servers: + development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests." + production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." +``` + +### `Tags` in `Channels` object +Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only impact the `channels` object of the AsyncAPI document. + +Here's a visual representation of `tags` object inside a `channels` object in a AsyncAPI document: +```marmaid +graph LR + A[channel] + B(address) + C(title) + D(description) + E(messages) + H(parameters) + J(servers) + M(bindings) + P(tags) + R(externalDocs) + F(name) + G(description) + I(externalDocs) + Z(asyncapi) + + Z --> A + A --> B + A --> C + A --> D + A --> E + A --> H + A --> J + A --> M + A --> P + A --> R + P --> F + P --> G + P --> I +``` + +Below is a example of the `tags` object inside the `channels` object in a AsyncAPI document: +```yaml +channels: + SignedUp: + address: 'user.signedup' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + tags: + - name: user + description: User-related messages +``` + +### `Tags` in `Operations` Object +The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on type of operation or functionality and more. The `tags` object when used within a `operations` object, the context is restricted to the `operations` object and the individual `operation` of the AsyncAPI document, meaning they only impact the `operations` object of the AsyncAPI document. + +Here's a visual representation of `tags` object inside a `operations` object in a AsyncAPI document: +```mermaid +graph LR + A[operation] + B(title) + C(summary) + D(description) + E(channel) + F(action) + G(security) + H(tags) + I(bindings) + J(traits) + K(messages) + L(reply) + M(address) + N(channel) + W(asyncapi) + X(name) + Y(description) + Z(externalDocs) + + W --> A + A -->B + A --> C + A --> D + A -->E + A --> F + A --> G + A --> H + A --> I + A -->J + A --> K + A -->L + L --> M + L --> N + H --> X + H --> Y + H --> Z +``` + +Below is a example of the `tags` object inside the `operations` object in a AsyncAPI document: +```yaml +operations: + 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 + description: operation related to user + - name: signup + description: operation related to a user's signUp + - name: register + description: operation related to a new registration + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' +``` + +### `Tags` in `message` object +Tags are associated with individual message objects allowing for logical grouping and categorization of meassages based on specific requirements or criteria or given channel and operation and more. The `tags` object when used within a `message` object, the context is restricted to the `message` object of the AsyncAPI document, meaning they only impact the `message` object of the AsyncAPI document. + +Here's a visual representation of `tags` object inside a `message` object in a AsyncAPI document: +```mermaid +graph LR + A[message] --> B[summary] + A --> C[tags] + C --> D[name] + C --> E[description] + A --> F[headers] + F --> G[correlationId] + F --> H[applicationInstanceId] + A --> I[payload] +``` + +Below is a example of the `tags` object inside the `message` object in a AsyncAPI document: +```yaml + name: SimpleSignup +summary: A simple UserSignup example message +tags: + - name: userSignUp + description: some message related to user signup +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + From fa12715dc8fd045570c090084bc848e73ca2d45d Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Sun, 16 Jul 2023 14:31:14 +0530 Subject: [PATCH 02/13] fix: grammar and spelling check --- pages/docs/concepts/asyncapi-document/tags.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 0d72004d4da..7cad5afb570 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -9,18 +9,18 @@ A `tag` is a label or category that helps you logically group related objects su The `tags` object serves as a container for defining and managing tags in a systematic manner. Within the `tags` object, you can define individual tags, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. -Once tags are defined within the `tags` object, they can be assigned to channels, operations or any other component using the tags property. By including the relevant tag names in the tags property, objects such as channels, servers or components are associated with the appropriate tags, grouping them together based on their shared characteristics. +Once tags are defined within the `tags` object, they can be assigned to channels, operations or any other component using the tags property. By including the relevant tag names in the tags property, objects such as channels, servers or components are associated with the appropriate tags, grouping them based on their shared characteristics. -Additionally, `tags` can also be included in the [`components` object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#componentsObject) of a AsyncAPI document, which enables the reusuability of the tags. `tags` included in the `components` object can re-used by [reference objects](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). +Additionally, `tags` can also be included in the [`components` object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by [reference objects](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). ## `Tags` in AsyncAPI Document The `tags` object is a list of `tag` objects which can be referenced by [reference object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). The `tags` object within the AsyncAPI specification contains some fields that define and describe individual tags. -The behavior and impact of the `tags` object within the AsyncAPI document can vary depending on the context of the object in which it is being used. For instance, The way `tags` object impacts a server object is different from when it is used under the channels object. +The behaviour and impact of the `tags` object within the AsyncAPI document can vary depending on the context of the object in which it is being used. For instance, The way the `tags` object impacts a server object is different from when it is used under the channels object. -Some of the fields that `tags` object holds are: +Some of the fields that the `tags` object holds are: - `name`: The name of the tag. - `description`: A short description for the tag. - `externalDocs`: Additional external documentation for this tag. @@ -28,7 +28,7 @@ Some of the fields that `tags` object holds are: ### `Tags` in `Info` Object Tags when defined within the `tags` property of the `info` object provides a high-level categorization and classification for the entire AsyncAPI document. These tags that are defined under the `info` object give a global context to the entire application, representing overarching themes or functional areas within the event-driven system. They serve as a way to group objects such as channels or servers based on their broader significance, providing a holistic understanding of the application's structure. -Here's a visual representation of `tags` object inside a `info` object in a AsyncAPI document: +Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: ```mermaid graph LR A[asyncapi] --> B[info] @@ -41,7 +41,7 @@ graph LR F --> K[externalDocs] ``` -Below is a example of the `tags` object inside the `info` object in a AsyncAPI document: +Below is an example of the `tags` object inside the `info` object in an AsyncAPI document: ```yaml asyncapi: 3.0.0 info: @@ -60,9 +60,9 @@ info: ``` ### `Tags` in `Servers` Object -Tags when used within the `tags` property of the `servers` object, they are specific to the servers configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using tags in servers object allows for the categorization and organization of servers based on specific tags or labels. +Tags when used within the `tags` property of the `servers` object, are specific to the servers' configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using tags in servers object allows for the categorization and organization of servers based on specific tags or labels. -Here's a visual representation of `tags` object inside a `servers` object in a AsyncAPI document: +Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: ```mermaid graph LR A[asyncapi] --> B[servers] @@ -76,7 +76,7 @@ graph LR G --> J[externalDocs] ``` -Below is a example of the `tags` object inside the `servers` object in a AsyncAPI document: +Below is an example of the `tags` object inside the `servers` object in an AsyncAPI document: ```yaml servers: development: @@ -100,8 +100,8 @@ servers: ### `Tags` in `Channels` object Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only impact the `channels` object of the AsyncAPI document. -Here's a visual representation of `tags` object inside a `channels` object in a AsyncAPI document: -```marmaid +Here's a visual representation of the `tags` object inside a `channels` object in an AsyncAPI document: +```mermaid graph LR A[channel] B(address) @@ -133,7 +133,7 @@ graph LR P --> I ``` -Below is a example of the `tags` object inside the `channels` object in a AsyncAPI document: +Below is an example of the `tags` object inside the `channels` object in an AsyncAPI document: ```yaml channels: SignedUp: @@ -147,9 +147,9 @@ channels: ``` ### `Tags` in `Operations` Object -The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on type of operation or functionality and more. The `tags` object when used within a `operations` object, the context is restricted to the `operations` object and the individual `operation` of the AsyncAPI document, meaning they only impact the `operations` object of the AsyncAPI document. +The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within a `operations` object, the context is restricted to the `operations` object and the individual `operation` of the AsyncAPI document, meaning they only impact the `operations` object of the AsyncAPI document. -Here's a visual representation of `tags` object inside a `operations` object in a AsyncAPI document: +Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: ```mermaid graph LR A[operation] @@ -172,17 +172,17 @@ graph LR Z(externalDocs) W --> A - A -->B + A --> B A --> C A --> D - A -->E + A --> E A --> F A --> G A --> H A --> I - A -->J + A --> J A --> K - A -->L + A --> L L --> M L --> N H --> X @@ -190,7 +190,7 @@ graph LR H --> Z ``` -Below is a example of the `tags` object inside the `operations` object in a AsyncAPI document: +Below is an example of the `tags` object inside the `operations` object in an AsyncAPI document: ```yaml operations: onUserSignUp: @@ -215,9 +215,9 @@ operations: ``` ### `Tags` in `message` object -Tags are associated with individual message objects allowing for logical grouping and categorization of meassages based on specific requirements or criteria or given channel and operation and more. The `tags` object when used within a `message` object, the context is restricted to the `message` object of the AsyncAPI document, meaning they only impact the `message` object of the AsyncAPI document. +Tags are associated with individual message objects allowing for logical grouping and categorization of messages based on specific requirements or criteria or given channels and operations and more. The `tags` object when used within a `message` object, the context is restricted to the `message` object of the AsyncAPI document, meaning they only impact the `message` object of the AsyncAPI document. -Here's a visual representation of `tags` object inside a `message` object in a AsyncAPI document: +Here's a visual representation of a `tags` object inside a `message` object in an AsyncAPI document: ```mermaid graph LR A[message] --> B[summary] @@ -230,7 +230,7 @@ graph LR A --> I[payload] ``` -Below is a example of the `tags` object inside the `message` object in a AsyncAPI document: +Below is an example of the `tags` object inside the `message` object in an AsyncAPI document: ```yaml name: SimpleSignup summary: A simple UserSignup example message From 8fb07cf06d972f07b762ce8bb7ae3daba0e15453 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 18 Oct 2023 02:41:29 +0530 Subject: [PATCH 03/13] fix: edits suggested by Lukasz & Alejandra --- pages/docs/concepts/asyncapi-document/tags.md | 77 +++++++++++++------ 1 file changed, 53 insertions(+), 24 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 7cad5afb570..a7999c09ea3 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -3,22 +3,20 @@ title: 'Tags' weight: 63 --- ---- Unique Description about AsyncAPI document to be inserted here --- +A tag is a label or category that helps you logically group related objects such as channels or servers within an event-driven system. The `tag` object enables you to group channels, operations or other components based on their functionality, purpose and/or any other relevant criteria. -A `tag` is a label or category that helps you logically group related objects such as channels or servers within an event-driven system. The `tags` object provide a structured way to group channels, operations or other components based on their functionality, purpose and/or any other relevant criteria. +In AyncAPI, the `tags` object is essentially a list of `tag` objects. Within the `tags` object, you can define individual `tag`s, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. -The `tags` object serves as a container for defining and managing tags in a systematic manner. Within the `tags` object, you can define individual tags, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. +`tags` can be defined in the [`components` object](../../reference/specification/v3.0.0-next-major-spec.12.md#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](../../reference/specification/v3.0.0-next-major-spec.12.md#referenceObject). -Once tags are defined within the `tags` object, they can be assigned to channels, operations or any other component using the tags property. By including the relevant tag names in the tags property, objects such as channels, servers or components are associated with the appropriate tags, grouping them based on their shared characteristics. - -Additionally, `tags` can also be included in the [`components` object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by [reference objects](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). +Additionally, you can define a list of tags you wanna use across the document under the `tags` object on the `info` level and you can reuse those tags under individual components such as `servers` or `channels` allowing you to group components logically. ## `Tags` in AsyncAPI Document -The `tags` object is a list of `tag` objects which can be referenced by [reference object](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#referenceObject). +The `tags` object is a list of `tag` objects that can be referenced by [reference object](../../reference/specification/v3.0.0-next-major-spec.12.md#referenceObject). -The `tags` object within the AsyncAPI specification contains some fields that define and describe individual tags. +The `tags` object is a list of tags and individual `tag` objects contain some fields. -The behaviour and impact of the `tags` object within the AsyncAPI document can vary depending on the context of the object in which it is being used. For instance, The way the `tags` object impacts a server object is different from when it is used under the channels object. +The behaviour of tags inside the `tags` object in the AsyncAPI document can vary based on the context of the object it is being used in. For instance, you can use the `tags` object to have tags used consistently across the AsyncAPI document for logical grouping of components or you can use tags under individual components like on `servers` or `channels` for a specific purpose. Some of the fields that the `tags` object holds are: - `name`: The name of the tag. @@ -26,7 +24,7 @@ Some of the fields that the `tags` object holds are: - `externalDocs`: Additional external documentation for this tag. ### `Tags` in `Info` Object -Tags when defined within the `tags` property of the `info` object provides a high-level categorization and classification for the entire AsyncAPI document. These tags that are defined under the `info` object give a global context to the entire application, representing overarching themes or functional areas within the event-driven system. They serve as a way to group objects such as channels or servers based on their broader significance, providing a holistic understanding of the application's structure. +When defined within the `tags` property of the info object, tags provide a high-level categorization and classification for the entire AsyncAPI document. These tags that are defined under the `info` object give a global context to the entire application, representing overarching themes or functional areas within the event-driven system. They serve as a way to group objects such as channels or servers based on their broader significance, providing a holistic understanding of the application's structure. Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: ```mermaid @@ -39,6 +37,13 @@ graph LR F --> G[name] F --> I[description] F --> K[externalDocs] + + style A fill:#47BCEE,stroke:#000; + style B fill:#47BCEE,stroke:#000; + style F fill:#47BCEE,stroke:#000; + style I fill:#47BCEE,stroke:#000; + style K fill:#47BCEE,stroke:#000; + style G fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `info` object in an AsyncAPI document: @@ -48,19 +53,19 @@ info: title: AsyncAPI Documentation version: 1.0.0 description: | - This AsyncAPI document provides a overview + This AsyncAPI document provides an overview of the event-driven system. tags: - - name: Finance - description: APIs related to financial transactions - - name: Customer - description: APIs related to customer interactions - - name: Inventory - description: APIs related to inventory management + - name: Applications + description: All applications related topics. + url: https://applications.example.com/docs + - name: Time + description: All time related topics. + url: https://time.example.com/docs ``` ### `Tags` in `Servers` Object -Tags when used within the `tags` property of the `servers` object, are specific to the servers' configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using tags in servers object allows for the categorization and organization of servers based on specific tags or labels. +Tags when used within the `tags` property of the `servers` object, are specific to the servers' configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using `tags` in `servers` object allows for the categorization and organization of servers based on specific tags or labels. Using `tags` object under the `servers` object is optional. Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: ```mermaid @@ -74,6 +79,12 @@ graph LR G --> H[name] G --> I[description] G --> J[externalDocs] + style A fill:#47BCEE,stroke:#000; + style B fill:#47BCEE,stroke:#000; + style G fill:#47BCEE,stroke:#000; + style I fill:#47BCEE,stroke:#000; + style H fill:#47BCEE,stroke:#000; + style J fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `servers` object in an AsyncAPI document: @@ -86,7 +97,7 @@ servers: protocolVersion: 0-9-1 tags: - name: "env:development" - description: "This environment is meant for developers to run their own tests." + description: "This environment is meant for developers to run their tests." production: host: rabbitmq.in.mycompany.com:5672 description: RabbitMQ broker for the production environment. @@ -98,7 +109,8 @@ servers: ``` ### `Tags` in `Channels` object -Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only impact the `channels` object of the AsyncAPI document. +Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is either restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only affect the `channels` object of the AsyncAPI document or they could be used for consistency of tags across the document for logical grouping. Using `tags` object under the `channels` object is optional. + Here's a visual representation of the `tags` object inside a `channels` object in an AsyncAPI document: ```mermaid @@ -131,6 +143,12 @@ graph LR P --> F P --> G P --> I + style A fill:#47BCEE,stroke:#000; + style Z fill:#47BCEE,stroke:#000; + style P fill:#47BCEE,stroke:#000; + style F fill:#47BCEE,stroke:#000; + style G fill:#47BCEE,stroke:#000; + style I fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `channels` object in an AsyncAPI document: @@ -147,7 +165,7 @@ channels: ``` ### `Tags` in `Operations` Object -The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within a `operations` object, the context is restricted to the `operations` object and the individual `operation` of the AsyncAPI document, meaning they only impact the `operations` object of the AsyncAPI document. +The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within an `operations` object, it can either only affect the `operations` object for a specific purpose or it could be to be in consistent use of tags for logical grouping of components. Using the `tags` object in `operations` object is optional. Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: ```mermaid @@ -188,6 +206,12 @@ graph LR H --> X H --> Y H --> Z + style A fill:#47BCEE,stroke:#000; + style Z fill:#47BCEE,stroke:#000; + style W fill:#47BCEE,stroke:#000; + style H fill:#47BCEE,stroke:#000; + style Y fill:#47BCEE,stroke:#000; + style X fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `operations` object in an AsyncAPI document: @@ -215,7 +239,7 @@ operations: ``` ### `Tags` in `message` object -Tags are associated with individual message objects allowing for logical grouping and categorization of messages based on specific requirements or criteria or given channels and operations and more. The `tags` object when used within a `message` object, the context is restricted to the `message` object of the AsyncAPI document, meaning they only impact the `message` object of the AsyncAPI document. +Tags are associated with individual message objects allowing for logical grouping and categorization of messages based on specific requirements or criteria or given channels and operations and more. The `tags` object when used within a `message` object, the context is either restricted to the `message` object of the AsyncAPI document, meaning they only affect the `message` object of the AsyncAPI document or it could be a part of consistent use of tags across the document for logical grouping. Here's a visual representation of a `tags` object inside a `message` object in an AsyncAPI document: ```mermaid @@ -228,6 +252,12 @@ graph LR F --> G[correlationId] F --> H[applicationInstanceId] A --> I[payload] + C --> Y[externalDocs] + style A fill:#47BCEE,stroke:#000; + style D fill:#47BCEE,stroke:#000; + style C fill:#47BCEE,stroke:#000; + style E fill:#47BCEE,stroke:#000; + style Y fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `message` object in an AsyncAPI document: @@ -245,5 +275,4 @@ payload: someUserKey: someUserValue signup: someSignupKey: someSignupValue -``` - +``` \ No newline at end of file From c2ecfc468403e38bae148abc9313820ec3e53232 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 18 Oct 2023 02:57:22 +0530 Subject: [PATCH 04/13] add: summary example --- pages/docs/concepts/asyncapi-document/tags.md | 84 ++++++++++++++++++- 1 file changed, 81 insertions(+), 3 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index a7999c09ea3..987a8b8dcf7 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -65,7 +65,7 @@ info: ``` ### `Tags` in `Servers` Object -Tags when used within the `tags` property of the `servers` object, are specific to the servers' configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using `tags` in `servers` object allows for the categorization and organization of servers based on specific tags or labels. Using `tags` object under the `servers` object is optional. +Tags when used within the `tags` property of the `servers` object, are specific to the servers' configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using `tags` in the `servers` object allows for the categorization and organization of servers based on specific tags or labels. Using the `tags` object under the `servers` object is optional. Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: ```mermaid @@ -109,7 +109,7 @@ servers: ``` ### `Tags` in `Channels` object -Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is either restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only affect the `channels` object of the AsyncAPI document or they could be used for consistency of tags across the document for logical grouping. Using `tags` object under the `channels` object is optional. +Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is either restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only affect the `channels` object of the AsyncAPI document or they could be used for consistency of tags across the document for logical grouping. Using the `tags` object under the `channels` object is optional. Here's a visual representation of the `tags` object inside a `channels` object in an AsyncAPI document: @@ -165,7 +165,7 @@ channels: ``` ### `Tags` in `Operations` Object -The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within an `operations` object, it can either only affect the `operations` object for a specific purpose or it could be to be in consistent use of tags for logical grouping of components. Using the `tags` object in `operations` object is optional. +The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within an `operations` object, it can either only affect the `operations` object for a specific purpose or it could be to be in consistent use of tags for logical grouping of components. Using the `tags` object in the `operations` object is optional. Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: ```mermaid @@ -275,4 +275,82 @@ payload: someUserKey: someUserValue signup: someSignupKey: someSignupValue +``` + +## Example +Here's an example illustrating all the tags being defined in the `components` object and then referenced in other components such as `servers`, `channels` and more: +```yml +asyncapi: 3.0.0 + +components: + tags: + speech: + name: Speech + description: All speech related topics. + video: + name: Video + description: All video related topics. + +info: + title: AsyncAPI Documentation + version: 1.0.0 + description: | + This AsyncAPI document provides an overview + of the event-driven system. + tags: + - $ref: '#/components/tags/speech' + - $ref: '#/components/tags/audio' + +servers: + speech: + host: localhost:5672 + description: RabbitMQ broker for sending speech data. + protocol: amqp + tags: + - $ref: '#/components/tags/speech' + video: + host: localhost:5673 + description: RabbitMQ broker for audio information. + protocol: amqp + tags: + - $ref: '#/components/tags/video' + +channels: + getSpeech: + address: 'application/speech/get' + servers: + - $ref: '#/servers/speech' + messages: + voice: + name: Voice + summary: Add info about the voice stream data. + tags: + - $ref: '#/components/tags/speech' + getVideo: + address: 'application/video/get' + servers: + - $ref: '#/servers/video' + messages: + voice: + name: Video + summary: Add info about the video data live bitrate and others. + tags: + - $ref: '#/components/tags/video' + +operations: + onVoiceStreamed: + title: Get speech data + channel: + $ref: '#/channels/getSpeech' + action: receive + tags: + - $ref: '#/components/tags/speech' + + onVideoStreamed: + title: Get video data + channel: + $ref: '#/channels/getVideo' + action: receive + tags: + - $ref: '#/components/tags/video' ``` \ No newline at end of file From 5a3b8e5bb0cbd72b6304a51aa7e68f6693cb765f Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 25 Oct 2023 12:52:44 +0530 Subject: [PATCH 05/13] Update code examples --- pages/docs/concepts/asyncapi-document/tags.md | 55 ++++++++++++------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 987a8b8dcf7..1ce19129284 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -58,10 +58,14 @@ info: tags: - name: Applications description: All applications related topics. - url: https://applications.example.com/docs + externalDocs: + description: More info about applications + url: https://applications.example.com/docs - name: Time description: All time related topics. - url: https://time.example.com/docs + externalDocs: + description: More info about time + url: https://time.example.com/docs ``` ### `Tags` in `Servers` Object @@ -89,23 +93,29 @@ graph LR Below is an example of the `tags` object inside the `servers` object in an AsyncAPI document: ```yaml +asyncapi: 3.0.0 + +info: + title: AsyncAPI Documentation + version: 1.0.0 + servers: - development: - host: localhost:5672 - description: Development AMQP broker. - protocol: amqp - protocolVersion: 0-9-1 - tags: - - name: "env:development" - description: "This environment is meant for developers to run their tests." - production: - host: rabbitmq.in.mycompany.com:5672 - description: RabbitMQ broker for the production environment. - protocol: amqp - protocolVersion: 0-9-1 - tags: - - name: "env:production" - description: "This environment is the live environment available for final users." + development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their tests." + production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." ``` ### `Tags` in `Channels` object @@ -153,12 +163,19 @@ graph LR Below is an example of the `tags` object inside the `channels` object in an AsyncAPI document: ```yaml +asyncapi: 3.0.0 + +info: + title: AsyncAPI Documentation + version: 1.0.0 + channels: SignedUp: address: 'user.signedup' messages: userSignedUp: - $ref: '#/components/messages/userSignedUp' + payload: + type: object tags: - name: user description: User-related messages From 967f8e61bcf1e4d405a7f677d3b96966b14d172d Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 25 Oct 2023 13:16:21 +0530 Subject: [PATCH 06/13] Update diagrams --- pages/docs/concepts/asyncapi-document/tags.md | 25 ------------------- 1 file changed, 25 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 1ce19129284..19bb048617d 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -78,7 +78,6 @@ graph LR B --> C[host] B --> D[description] B --> E[protocol] - B --> F[protocolVersion] B --> G[tags] G --> H[name] G --> I[description] @@ -127,14 +126,9 @@ Here's a visual representation of the `tags` object inside a `channels` object i graph LR A[channel] B(address) - C(title) D(description) E(messages) - H(parameters) - J(servers) - M(bindings) P(tags) - R(externalDocs) F(name) G(description) I(externalDocs) @@ -142,14 +136,9 @@ graph LR Z --> A A --> B - A --> C A --> D A --> E - A --> H - A --> J - A --> M A --> P - A --> R P --> F P --> G P --> I @@ -188,16 +177,9 @@ Here's a visual representation of the `tags` object inside a `operations` object ```mermaid graph LR A[operation] - B(title) - C(summary) - D(description) E(channel) F(action) - G(security) H(tags) - I(bindings) - J(traits) - K(messages) L(reply) M(address) N(channel) @@ -207,16 +189,9 @@ graph LR Z(externalDocs) W --> A - A --> B - A --> C - A --> D A --> E A --> F - A --> G A --> H - A --> I - A --> J - A --> K A --> L L --> M L --> N From 17eef859fd498897aadcdbcc3054af58430e6a75 Mon Sep 17 00:00:00 2001 From: Rohit Date: Tue, 7 Nov 2023 12:19:17 +0530 Subject: [PATCH 07/13] update diagrams to component level --- pages/docs/concepts/asyncapi-document/tags.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 19bb048617d..57aeafd7a65 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -29,16 +29,15 @@ When defined within the `tags` property of the info object, tags provide a high- Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: ```mermaid graph LR - A[asyncapi] --> B[info] + B[info] B --> C[title] B --> D[version] - B --> E[description] B --> F[tags] F --> G[name] F --> I[description] F --> K[externalDocs] - style A fill:#47BCEE,stroke:#000; + style B fill:#47BCEE,stroke:#000; style F fill:#47BCEE,stroke:#000; style I fill:#47BCEE,stroke:#000; @@ -74,15 +73,13 @@ Tags when used within the `tags` property of the `servers` object, are specific Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: ```mermaid graph LR - A[asyncapi] --> B[servers] + B[servers] B --> C[host] - B --> D[description] B --> E[protocol] B --> G[tags] G --> H[name] G --> I[description] G --> J[externalDocs] - style A fill:#47BCEE,stroke:#000; style B fill:#47BCEE,stroke:#000; style G fill:#47BCEE,stroke:#000; style I fill:#47BCEE,stroke:#000; @@ -126,24 +123,19 @@ Here's a visual representation of the `tags` object inside a `channels` object i graph LR A[channel] B(address) - D(description) E(messages) P(tags) F(name) G(description) I(externalDocs) - Z(asyncapi) - Z --> A A --> B - A --> D A --> E A --> P P --> F P --> G P --> I style A fill:#47BCEE,stroke:#000; - style Z fill:#47BCEE,stroke:#000; style P fill:#47BCEE,stroke:#000; style F fill:#47BCEE,stroke:#000; style G fill:#47BCEE,stroke:#000; @@ -183,12 +175,10 @@ graph LR L(reply) M(address) N(channel) - W(asyncapi) X(name) Y(description) Z(externalDocs) - - W --> A + A --> E A --> F A --> H @@ -200,7 +190,6 @@ graph LR H --> Z style A fill:#47BCEE,stroke:#000; style Z fill:#47BCEE,stroke:#000; - style W fill:#47BCEE,stroke:#000; style H fill:#47BCEE,stroke:#000; style Y fill:#47BCEE,stroke:#000; style X fill:#47BCEE,stroke:#000; From 722caea9f6ad9594196807253aeba1c8bd33a310 Mon Sep 17 00:00:00 2001 From: Rohit Date: Tue, 7 Nov 2023 12:21:10 +0530 Subject: [PATCH 08/13] Fix broken links --- pages/docs/concepts/asyncapi-document/tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 57aeafd7a65..12d7cb9669a 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -7,12 +7,12 @@ A tag is a label or category that helps you logically group related objects such In AyncAPI, the `tags` object is essentially a list of `tag` objects. Within the `tags` object, you can define individual `tag`s, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. -`tags` can be defined in the [`components` object](../../reference/specification/v3.0.0-next-major-spec.12.md#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](../../reference/specification/v3.0.0-next-major-spec.12.md#referenceObject). +`tags` can be defined in the [`components` object](../../reference/specification/v3.0.0-next-major-spec.12#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](../../reference/specification/v3.0.0-next-major-spec.12#referenceObject). Additionally, you can define a list of tags you wanna use across the document under the `tags` object on the `info` level and you can reuse those tags under individual components such as `servers` or `channels` allowing you to group components logically. ## `Tags` in AsyncAPI Document -The `tags` object is a list of `tag` objects that can be referenced by [reference object](../../reference/specification/v3.0.0-next-major-spec.12.md#referenceObject). +The `tags` object is a list of `tag` objects that can be referenced by [reference object](../../reference/specification/v3.0.0-next-major-spec.12#referenceObject). The `tags` object is a list of tags and individual `tag` objects contain some fields. From ee2bbc72ddc01c50c94b75d1120fbfddc9dc7286 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 8 Nov 2023 21:25:43 +0530 Subject: [PATCH 09/13] Update links to match V3 ref --- pages/docs/concepts/asyncapi-document/tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 12d7cb9669a..c2c648c26d9 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -7,12 +7,12 @@ A tag is a label or category that helps you logically group related objects such In AyncAPI, the `tags` object is essentially a list of `tag` objects. Within the `tags` object, you can define individual `tag`s, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. -`tags` can be defined in the [`components` object](../../reference/specification/v3.0.0-next-major-spec.12#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](../../reference/specification/v3.0.0-next-major-spec.12#referenceObject). +`tags` can be defined in the [`components` object](/pages/docs/reference/specification/latest#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](/pages/docs/reference/specification/latest#referenceObject). Additionally, you can define a list of tags you wanna use across the document under the `tags` object on the `info` level and you can reuse those tags under individual components such as `servers` or `channels` allowing you to group components logically. ## `Tags` in AsyncAPI Document -The `tags` object is a list of `tag` objects that can be referenced by [reference object](../../reference/specification/v3.0.0-next-major-spec.12#referenceObject). +The `tags` object is a list of `tag` objects that can be referenced by [reference object](/pages/docs/reference/specification/latest#referenceObject). The `tags` object is a list of tags and individual `tag` objects contain some fields. From 50e208bf1b20c8280993905a34931b4be6e0fb29 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 8 Nov 2023 21:31:43 +0530 Subject: [PATCH 10/13] re-update links --- pages/docs/concepts/asyncapi-document/tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index c2c648c26d9..1053cece11c 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -7,12 +7,12 @@ A tag is a label or category that helps you logically group related objects such In AyncAPI, the `tags` object is essentially a list of `tag` objects. Within the `tags` object, you can define individual `tag`s, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. -`tags` can be defined in the [`components` object](/pages/docs/reference/specification/latest#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](/pages/docs/reference/specification/latest#referenceObject). +`tags` can be defined in the [`components` object](/docs/reference/specification/latest#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](/docs/reference/specification/latest#referenceObject). Additionally, you can define a list of tags you wanna use across the document under the `tags` object on the `info` level and you can reuse those tags under individual components such as `servers` or `channels` allowing you to group components logically. ## `Tags` in AsyncAPI Document -The `tags` object is a list of `tag` objects that can be referenced by [reference object](/pages/docs/reference/specification/latest#referenceObject). +The `tags` object is a list of `tag` objects that can be referenced by [reference object](/docs/reference/specification/latest#referenceObject). The `tags` object is a list of tags and individual `tag` objects contain some fields. From f5c81d39d05a7d36d7ae29dfcbb5396986448660 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 15 Nov 2023 17:22:29 +0100 Subject: [PATCH 11/13] Update tags.md --- pages/docs/concepts/asyncapi-document/tags.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 1053cece11c..6ed4f1beabc 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -12,6 +12,7 @@ In AyncAPI, the `tags` object is essentially a list of `tag` objects. Within the Additionally, you can define a list of tags you wanna use across the document under the `tags` object on the `info` level and you can reuse those tags under individual components such as `servers` or `channels` allowing you to group components logically. ## `Tags` in AsyncAPI Document + The `tags` object is a list of `tag` objects that can be referenced by [reference object](/docs/reference/specification/latest#referenceObject). The `tags` object is a list of tags and individual `tag` objects contain some fields. @@ -24,6 +25,7 @@ Some of the fields that the `tags` object holds are: - `externalDocs`: Additional external documentation for this tag. ### `Tags` in `Info` Object + When defined within the `tags` property of the info object, tags provide a high-level categorization and classification for the entire AsyncAPI document. These tags that are defined under the `info` object give a global context to the entire application, representing overarching themes or functional areas within the event-driven system. They serve as a way to group objects such as channels or servers based on their broader significance, providing a holistic understanding of the application's structure. Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: @@ -115,6 +117,7 @@ servers: ``` ### `Tags` in `Channels` object + Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is either restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only affect the `channels` object of the AsyncAPI document or they could be used for consistency of tags across the document for logical grouping. Using the `tags` object under the `channels` object is optional. @@ -163,6 +166,7 @@ channels: ``` ### `Tags` in `Operations` Object + The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within an `operations` object, it can either only affect the `operations` object for a specific purpose or it could be to be in consistent use of tags for logical grouping of components. Using the `tags` object in the `operations` object is optional. Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: @@ -172,9 +176,6 @@ graph LR E(channel) F(action) H(tags) - L(reply) - M(address) - N(channel) X(name) Y(description) Z(externalDocs) @@ -182,9 +183,6 @@ graph LR A --> E A --> F A --> H - A --> L - L --> M - L --> N H --> X H --> Y H --> Z @@ -220,6 +218,7 @@ operations: ``` ### `Tags` in `message` object + Tags are associated with individual message objects allowing for logical grouping and categorization of messages based on specific requirements or criteria or given channels and operations and more. The `tags` object when used within a `message` object, the context is either restricted to the `message` object of the AsyncAPI document, meaning they only affect the `message` object of the AsyncAPI document or it could be a part of consistent use of tags across the document for logical grouping. Here's a visual representation of a `tags` object inside a `message` object in an AsyncAPI document: @@ -230,8 +229,6 @@ graph LR C --> D[name] C --> E[description] A --> F[headers] - F --> G[correlationId] - F --> H[applicationInstanceId] A --> I[payload] C --> Y[externalDocs] style A fill:#47BCEE,stroke:#000; @@ -259,7 +256,9 @@ payload: ``` ## Example + Here's an example illustrating all the tags being defined in the `components` object and then referenced in other components such as `servers`, `channels` and more: + ```yml asyncapi: 3.0.0 @@ -280,7 +279,7 @@ info: of the event-driven system. tags: - $ref: '#/components/tags/speech' - - $ref: '#/components/tags/audio' + - $ref: '#/components/tags/video' servers: speech: @@ -291,7 +290,7 @@ servers: - $ref: '#/components/tags/speech' video: host: localhost:5673 - description: RabbitMQ broker for audio information. + description: RabbitMQ broker for video information. protocol: amqp tags: - $ref: '#/components/tags/video' @@ -334,4 +333,4 @@ operations: action: receive tags: - $ref: '#/components/tags/video' -``` \ No newline at end of file +``` From cfb9f83ccecab82e814ef17b10afda553c1d0760 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Thu, 16 Nov 2023 10:21:33 -0800 Subject: [PATCH 12/13] Delete duplicate _section.md --- pages/docs/concepts/asyncapi-document/_section.md | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 pages/docs/concepts/asyncapi-document/_section.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md deleted file mode 100644 index d7dea824ae2..00000000000 --- a/pages/docs/concepts/asyncapi-document/_section.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'AsyncAPI Document' -weight: 50 ---- \ No newline at end of file From 8fa52d8a0751cc5791eec116594fce53c9b58e08 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Thu, 16 Nov 2023 12:50:54 -0800 Subject: [PATCH 13/13] tw editorial fixes --- pages/docs/concepts/asyncapi-document/tags.md | 43 +++++++++---------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md index 6ed4f1beabc..5b2c4c348d5 100644 --- a/pages/docs/concepts/asyncapi-document/tags.md +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -3,30 +3,30 @@ title: 'Tags' weight: 63 --- -A tag is a label or category that helps you logically group related objects such as channels or servers within an event-driven system. The `tag` object enables you to group channels, operations or other components based on their functionality, purpose and/or any other relevant criteria. +A tag functions as a label or category for logically grouping related entities like channels or servers in an event-driven system. The `tag` object facilitates the organization of channels, operations, or other components, categorizing them based on functionality, purpose, or other relevant criteria. -In AyncAPI, the `tags` object is essentially a list of `tag` objects. Within the `tags` object, you can define individual `tag`s, specifying a name and providing an optional description that adds further context to the tag's purpose or usage. +In AyncAPI, the `tags` object is a list of individual `tag` objects. Each `tag` within this collection can be defined with a specific name, accompanied by an optional description that offers additional insight into the tag's intended purpose or usage. -`tags` can be defined in the [`components` object](/docs/reference/specification/latest#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. `tags` included in the `components` object can be re-used by using [reference objects](/docs/reference/specification/latest#referenceObject). +You can define `tags` in the [`components` object](/docs/reference/specification/latest#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. If you include `tags` in the `components` object, they can be re-used by using [reference objects](/docs/reference/specification/latest#referenceObject). -Additionally, you can define a list of tags you wanna use across the document under the `tags` object on the `info` level and you can reuse those tags under individual components such as `servers` or `channels` allowing you to group components logically. +Additionally, within AsyncAPI, you can create a list of tags in the `tags` object at the `info` level, specifying the tags you intend to use throughout the document. These predefined tags can then be applied to individual components like `servers` or `channels`, facilitating logical grouping and organization of these components. -## `Tags` in AsyncAPI Document +## `tags` in AsyncAPI document -The `tags` object is a list of `tag` objects that can be referenced by [reference object](/docs/reference/specification/latest#referenceObject). +The `tags` object consists of a list of `tag` objects, which can be referenced using the [reference object](/docs/reference/specification/latest#referenceObject). -The `tags` object is a list of tags and individual `tag` objects contain some fields. +The `tags` object is a list of tags and individual `tag` objects, each containing specific fields. -The behaviour of tags inside the `tags` object in the AsyncAPI document can vary based on the context of the object it is being used in. For instance, you can use the `tags` object to have tags used consistently across the AsyncAPI document for logical grouping of components or you can use tags under individual components like on `servers` or `channels` for a specific purpose. +In an AsyncAPI document, the function of tags within the `tags` object differs depending on context. For example, the `tags` object can be employed for consistent usage of tags across the document and logical grouping of components. Alternatively, tags can be applied to individual components such as `servers` or `channels`, serving more specific purposes within those contexts. -Some of the fields that the `tags` object holds are: +The `tags` object fields include: - `name`: The name of the tag. - `description`: A short description for the tag. -- `externalDocs`: Additional external documentation for this tag. +- `externalDocs`: Additional external documentation for the tag. -### `Tags` in `Info` Object +### `tags` in `info` object -When defined within the `tags` property of the info object, tags provide a high-level categorization and classification for the entire AsyncAPI document. These tags that are defined under the `info` object give a global context to the entire application, representing overarching themes or functional areas within the event-driven system. They serve as a way to group objects such as channels or servers based on their broader significance, providing a holistic understanding of the application's structure. +When specified in the `tags` property of the info object, tags offer a comprehensive categorization for the entire AsyncAPI document. These globally defined tags under the `info` object impart an overarching context, representing key themes or functional areas within the event-driven system. They effectively group elements like channels or servers by their broader relevance, providing a holistic understanding of the application's structure. Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: ```mermaid @@ -69,8 +69,8 @@ info: url: https://time.example.com/docs ``` -### `Tags` in `Servers` Object -Tags when used within the `tags` property of the `servers` object, are specific to the servers' configurations and relate to the server-level characteristics. These tags allow for the categorization of server instances based on their properties or criteria, such as geographical location, environment (e.g., production, development), or specific server capabilities. Using `tags` in the `servers` object allows for the categorization and organization of servers based on specific tags or labels. Using the `tags` object under the `servers` object is optional. +### `tags` in `servers` object +When tags are utilized within the `servers` object's `tags` property, they specifically pertain to server configurations and characteristics. These tags enable server categorization by various criteria, including geographical location, environment type (i.e., production or development), or unique server features. Using `tags` in the `servers` object allows for the categorization and organization of servers based on specific tags or labels. Using the `tags` object under the `servers` object is optional. Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: ```mermaid @@ -116,9 +116,9 @@ servers: description: "This environment is the live environment available for final users." ``` -### `Tags` in `Channels` object +### `tags` in `channels` object -Tags are associated with individual channels allowing for logical grouping and categorization of channels based on specific functionalities or business domains. The `tags` object when used within a `channels` object, the context is either restricted to the `channels` object and the individual `channel` of the AsyncAPI document, meaning they only affect the `channels` object of the AsyncAPI document or they could be used for consistency of tags across the document for logical grouping. Using the `tags` object under the `channels` object is optional. +Tags linked with individual channels enable logical grouping and categorization based on specific functionalities or business domains. When the `tags` object is used within a `channels` object in an AsyncAPI document, its context is either confined to the `channels` object, impacting only that section, or it can be employed for consistent tagging across the document for cohesive grouping. Using the `tags` object under the `channels` object is optional. Here's a visual representation of the `tags` object inside a `channels` object in an AsyncAPI document: @@ -165,9 +165,9 @@ channels: description: User-related messages ``` -### `Tags` in `Operations` Object +### `tags` in `operations` object -The `tags` object within the `operations` object of the AsyncAPI document allows for logical grouping and categorization of individual `operation` objects based on the type of operation or functionality and more. The `tags` object when used within an `operations` object, it can either only affect the `operations` object for a specific purpose or it could be to be in consistent use of tags for logical grouping of components. Using the `tags` object in the `operations` object is optional. +Within an AsyncAPI document, the `tags` object in the `operations` object facilitates logical grouping and categorization of `operation` objects by operation type, functionality, and more. When used in an `operations` object, the `tags` can either serve a specific purpose within that object or be employed for consistent, logical grouping of components across the document. Using the `tags` object in the `operations` object is optional. Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: ```mermaid @@ -217,9 +217,9 @@ operations: - $ref: '#/components/operationTraits/kafka' ``` -### `Tags` in `message` object +### `tags` in `message` object -Tags are associated with individual message objects allowing for logical grouping and categorization of messages based on specific requirements or criteria or given channels and operations and more. The `tags` object when used within a `message` object, the context is either restricted to the `message` object of the AsyncAPI document, meaning they only affect the `message` object of the AsyncAPI document or it could be a part of consistent use of tags across the document for logical grouping. +Tags linked to individual message objects in an AsyncAPI document enable logical grouping and categorization of messages based on specific criteria, requirements, channels, and operations. When implemented within a `message` object, the context of the `tags` object can be confined to that specific message or integrated as the strategy for consistent tagging and logical organization across the entire document. Here's a visual representation of a `tags` object inside a `message` object in an AsyncAPI document: ```mermaid @@ -255,9 +255,8 @@ payload: someSignupKey: someSignupValue ``` -## Example -Here's an example illustrating all the tags being defined in the `components` object and then referenced in other components such as `servers`, `channels` and more: +Here's an example illustrating all the tags being defined in the `components` object and then referenced in other components such as `servers`, `channels`, and more: ```yml asyncapi: 3.0.0