Skip to content

Commit

Permalink
docs(tags): improve writing style
Browse files Browse the repository at this point in the history 
- Made doc sections more consistent
- Replace duplicated styling in mermaid diagram with classes
- Update yaml examples to use consistent formatting and descriptions
  • Loading branch information
@bandantonio
bandantonio committed Nov 19, 2024
1 parent 6f15381 commit 8a283e1
Showing 1 changed file with 76 additions and 69 deletions.
145 changes: 76 additions & 69 deletions markdown/docs/concepts/asyncapi-document/tags.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -39,40 +33,43 @@ 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:
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:
- 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]
Expand All @@ -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
Expand All @@ -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]
Expand All @@ -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
Expand All @@ -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]
Expand All @@ -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'
Expand All @@ -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]
Expand All @@ -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
Expand All @@ -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
Expand All @@ -265,31 +262,31 @@ 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'
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'
Expand All @@ -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:
Expand All @@ -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'
Expand All @@ -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

0 comments on commit 8a283e1

Please sign in to comment.