From 8a283e16acb8a7252e66c71f618d4e63cc566cc5 Mon Sep 17 00:00:00 2001 From: Antonio Date: Tue, 19 Nov 2024 02:32:13 +0200 Subject: [PATCH] docs(tags): improve writing style - Made doc sections more consistent - Replace duplicated styling in mermaid diagram with classes - Update yaml examples to use consistent formatting and descriptions --- .../docs/concepts/asyncapi-document/tags.md | 145 +++++++++--------- 1 file changed, 76 insertions(+), 69 deletions(-) diff --git a/markdown/docs/concepts/asyncapi-document/tags.md b/markdown/docs/concepts/asyncapi-document/tags.md index b6d3b263dc23..c2c000435a7f 100644 --- a/markdown/docs/concepts/asyncapi-document/tags.md +++ b/markdown/docs/concepts/asyncapi-document/tags.md @@ -3,32 +3,26 @@ title: 'Tags' weight: 63 --- -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 AsyncAPI, 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. - -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, 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 +A tag is a label or category that groups related entities in an event-driven system. -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, each containing specific fields. +In the AsyncAPI document, tags are defined as a list of [`tag` objects][tag-object] within the [`tags` object][tags-object] at the [`info` level][info-field]. -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. +The individual `tags` field contains the following properties: -The `tags` object fields include: - `name`: The name of the tag. -- `description`: A short description for the tag. +- `description`: A short description explaining the tag's purpose or usage. - `externalDocs`: Additional external documentation for the tag. +Tags have different purposes depending on the context. They can either be used for consistent tag usage across the AsyncAPI document and logical component grouping or be applied to individual components like [`servers`][servers-field], [`channels`][channels-field], or [`operations`][operations-field] for more specific purposes. + +To reuse `tags`, you must define them in the [`components` object][components-object] of an AsyncAPI document and then use [reference objects][reference-object] to include them. + ### `tags` in `info` object +Tags specified in the `tags` property of the `info` object categorize the entire AsyncAPI document. These globally defined tags provide an overarching context, representing key themes or functional areas within the event-driven system. They group elements like channels or servers by relevance, offering 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. +Below is a visual representation of the `tags` object inside the `info` object in an AsyncAPI document: -Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: ```mermaid graph LR B[info] @@ -39,15 +33,12 @@ graph LR F --> I[description] F --> K[externalDocs] - - 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; + class B,F,I,K,G cyanColor; + classDef cyanColor fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `info` object in an AsyncAPI document: + ```yaml asyncapi: 3.0.0 info: @@ -55,24 +46,30 @@ info: version: 1.0.0 description: | This AsyncAPI document provides an overview - of the event-driven system. + of the event-driven system tags: - name: Applications - description: All applications related topics. + description: All applications related topics externalDocs: description: More info about applications url: https://applications.example.com/docs - name: Time - description: All time related topics. + description: All time related topics externalDocs: description: More info about time url: https://time.example.com/docs ``` ### `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. +Tags specified in the `tags` property of the `servers` object categorize server configurations and characteristics. They allow for server categorization based on: + +- criteria like location, environment type (like production or development), and unique server features. +- specific tags or labels. + +Using the `tags` object under `servers` is optional. + +Below is a visual representation of the `tags` object inside the `servers` object in an AsyncAPI document: -Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: ```mermaid graph LR B[servers] @@ -82,14 +79,13 @@ graph LR G --> H[name] G --> I[description] G --> J[externalDocs] - 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; + + class B,G,I,J,H cyanColor; + classDef cyanColor fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `servers` object in an AsyncAPI document: + ```yaml asyncapi: 3.0.0 @@ -100,28 +96,29 @@ info: servers: development: host: localhost:5672 - description: Development AMQP broker. + 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." + - 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. + 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." + - name: env:production + description: This environment is the live environment available for final users ``` ### `tags` in `channels` object +Tags specified in the `tags` property of the `channels` object enable logical grouping and categorization based on specific functionalities or business domains. -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. +Using the `tags` object under the `channels` object is optional. +Below is a visual representation of the `tags` object inside the `channels` object in an AsyncAPI document: -Here's a visual representation of the `tags` object inside a `channels` object in an AsyncAPI document: ```mermaid graph LR A[channel] @@ -138,14 +135,13 @@ graph LR P --> F P --> G P --> I - style A 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; + + class A,P,F,G,I cyanColor; + classDef cyanColor fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `channels` object in an AsyncAPI document: + ```yaml asyncapi: 3.0.0 @@ -166,10 +162,12 @@ channels: ``` ### `tags` in `operations` object +Tags specified in the `tags` property of the `operations` object facilitate logical grouping and categorization of `operation` objects by type, functionality, and more. + +Using the `tags` object under 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. +Below is a visual representation of the `tags` object inside the `operations` object in an AsyncAPI document: -Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: ```mermaid graph LR A[operation] @@ -186,19 +184,18 @@ graph LR H --> X H --> Y H --> Z - style A fill:#47BCEE,stroke:#000; - style Z fill:#47BCEE,stroke:#000; - style H fill:#47BCEE,stroke:#000; - style Y fill:#47BCEE,stroke:#000; - style X fill:#47BCEE,stroke:#000; + + class A,H,X,Y,Z cyanColor; + classDef cyanColor fill:#47BCEE,stroke:#000; ``` Below is an example of the `tags` object inside the `operations` object in an AsyncAPI document: + ```yaml operations: onUserSignUp: title: User sign up - summary: Action to sign a user up. + summary: Action to sign a user up description: A longer description channel: $ref: '#/channels/userSignup' @@ -218,10 +215,12 @@ operations: ``` ### `tags` in `message` object +Tags specified in the `tags` property of the `message` object group and categorize messages based on criteria, requirements, channels, and operations. + +Using the `tags` object under the `message` object is optional. -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. +Below is a visual representation of the `tags` object inside the `message` object in an 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] @@ -231,14 +230,13 @@ graph LR A --> F[headers] 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; + + class A,C,D,E,Y cyanColor; + classDef cyanColor fill:#47BCEE,stroke:#000; ``` 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 @@ -255,8 +253,7 @@ payload: someSignupKey: someSignupValue ``` - -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: +Below is an example of all the tags defined in the `components` object and referenced in other components like `servers` and `channels`: ```yml asyncapi: 3.0.0 @@ -265,17 +262,17 @@ components: tags: speech: name: Speech - description: All speech related topics. + description: All speech related topics video: name: Video - description: All video related topics. + 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. + of the event-driven system tags: - $ref: '#/components/tags/speech' - $ref: '#/components/tags/video' @@ -283,13 +280,13 @@ info: servers: speech: host: localhost:5672 - description: RabbitMQ broker for sending speech data. + description: RabbitMQ broker for sending speech data protocol: amqp tags: - $ref: '#/components/tags/speech' video: host: localhost:5673 - description: RabbitMQ broker for video information. + description: RabbitMQ broker for video information protocol: amqp tags: - $ref: '#/components/tags/video' @@ -302,7 +299,7 @@ channels: messages: voice: name: Voice - summary: Add info about the voice stream data. + summary: Add info about the voice stream data tags: - $ref: '#/components/tags/speech' getVideo: @@ -312,7 +309,7 @@ channels: messages: voice: name: Video - summary: Add info about the video data live bitrate and others. + summary: Add info about the video data live bitrate and others tags: - $ref: '#/components/tags/video' @@ -333,3 +330,13 @@ operations: tags: - $ref: '#/components/tags/video' ``` + +- [info-field]: /docs/concepts/asyncapi-document/structure#info-field +- [servers-field]: /docs/concepts/asyncapi-document/structure#servers-field +- [channels-field]: /docs/concepts/asyncapi-document/structure#channels-field +- [operations-field]: /docs/concepts/asyncapi-document/structure#operations-field +- [components-field]: /docs/concepts/asyncapi-document/structure#components-field +- [tag-object]: /docs/reference/specification/latest#tagObject +- [tags-object]: /docs/reference/specification/latest#tagsObject +- [components-object]: /docs/reference/specification/latest#componentsObject +- [reference-object]: /docs/reference/specification/latest#referenceObject \ No newline at end of file