From 68310b0df3164f1af35446257b5d6c65d56686e8 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 8 Aug 2023 17:34:59 +0600 Subject: [PATCH 1/6] add reuse trait page --- .../concepts/asyncapi-document/_section.md | 4 + .../asyncapi-document/reusing-traits.md | 184 ++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/reusing-traits.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/reusing-traits.md b/pages/docs/concepts/asyncapi-document/reusing-traits.md new file mode 100644 index 00000000000..edfe6315142 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/reusing-traits.md @@ -0,0 +1,184 @@ +--- +title: Reusing Traits +weight: 200 +--- + +Traits are a powerful way to define a group of properties that can be reused across multiple message objects within the specification. Reusing traits promotes code maintainability, reduces duplication, and makes your AsyncAPI documents cleaner and easier to manage. + +## Defining Traits + +Traits are defined under the `components` section of your AsyncAPI document, within `operationTraits`or `messageTraits`, depending on whether you want to apply them to operations or messages, respectively. Each trait is given a unique name and contains the properties that will be applied. + +```mermaid +graph TD + A[components] + B[operationTraits] + C[kafka] + D[bindings] + E[kafka] + F[clientId] + A --> B + B --> C + C --> D + D --> E + E --> F +``` + +Here's an example of a trait named `kafka`: + +```yml +components: + operationTraits: + kafka: + bindings: + kafka: + clientId: my-app-id +``` + +In this example, the `kafka` trait includes the `clientId` property for Kafka bindings. + +## Applying Traits to Operations + +Once a trait is defined, you can apply it to an operation using the `$ref` keyword in the `traits` section of the operation. The `$ref` value should point to the path of the trait within the `components` section. + +```mermaid +graph LR + A((User Signup Operation)) + B[traits] + C[$ref of kafka trait] + A-->B + B-->C +``` + +Here's applying the `kafka` trait to an operation: + +```yml +channel: + $ref: '#/channels/userSignup' +action: send +tags: + - name: user + - name: signup + - name: register +bindings: + amqp: + ack: false +traits: + - $ref: '#/components/operationTraits/kafka' +``` + +In this case, the `userSignup` operation in the `userSignup` channel applies the `kafka` trait, which includes the `clientId` property for Kafka bindings. + +## Applying Traits to Messages + +Traits can also be applied to `message` objects in the messages section of the AsyncAPI document. This is done using the `$ref` keyword within the `traits` section of the message object. + +```mermaid +graph TD + A[messages] + B[myMessage] + C[traits] + D[$ref] + E[payload] + F[type: object] + G[properties] + H[message] + I[type: string] + A --> B + B --> C + C --> D + B --> E + E --> F + F --> G + G --> H + H --> I +``` + +For example, let's say we have a trait named commonHeaders defined in messageTraits: + +```yml +components: + messageTraits: + commonHeaders: + headers: + - name: Content-Type + type: string +``` + +To apply this trait to a message object, you can do: + +```yml +channels: + userSignup: + publish: + message: + $ref: '#/components/messages/commonMessage' + traits: + - $ref: '#/components/messageTraits/commonHeaders' +``` + +In this example, the `commonHeaders` trait, which includes a `Content-Type` header, is applied to the `commonMessage` within the `userSignup` operation. + +## Trait Merging and Overriding + +Traits in AsyncAPI are merged into the message object using the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) protocol, which means that traits are merged into the operation or message object, and any conflicting properties will be overridden based on the order of evaluation. + +```mermaid +graph TD + A[channels] + B[userSignup] + C[publish] + D[operationId] + E[bindings] + F[kafka] + G[clientId] + H[traits] + I[$ref] + A --> B + B --> C + C --> D + C --> E + E --> F + F --> G + C --> H + H --> I + +``` + +For example, let's consider the following trait and operation: + +```yml +components: + operationTraits: + kafka: + bindings: + kafka: + clientId: my-app-id + groupId: default-group + +channels: + userSignup: + publish: + operationId: userSignup + traits: + - $ref: '#/components/operationTraits/kafka' + bindings: + kafka: + groupId: custom-group +``` + +In this case, the operation applies the `kafka` trait, which provides the default `clientId` and `groupId` properties. However, in the operation itself, the `groupId` property is overridden with a custom value. The final result would be: + +```yml +channels: + userSignup: + publish: + operationId: userSignup + bindings: + kafka: + clientId: my-custom-app-id # this will override the clientId defined in trait + traits: + - $ref: '#/components/operationTraits/kafka' +``` + +As demonstrated, the `groupId` property defined in the operation overrides the value defined in the trait. From f299242257170882f82aecfbe261b5794ce517cb Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 8 Aug 2023 21:59:45 +0600 Subject: [PATCH 2/6] updating code --- .../asyncapi-document/reusing-traits.md | 145 ++++-------------- 1 file changed, 33 insertions(+), 112 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/reusing-traits.md b/pages/docs/concepts/asyncapi-document/reusing-traits.md index edfe6315142..c095284672a 100644 --- a/pages/docs/concepts/asyncapi-document/reusing-traits.md +++ b/pages/docs/concepts/asyncapi-document/reusing-traits.md @@ -11,32 +11,15 @@ Traits are defined under the `components` section of your AsyncAPI document, wit ```mermaid graph TD - A[components] - B[operationTraits] - C[kafka] - D[bindings] - E[kafka] - F[clientId] - A --> B - B --> C - C --> D - D --> E - E --> F -``` - -Here's an example of a trait named `kafka`: - -```yml -components: - operationTraits: - kafka: - bindings: - kafka: - clientId: my-app-id + A[AsyncAPI Document] --> B{Components} + B --> C[operationTraits] + B --> D[messageTraits] + C --> E{Trait 1} + D --> G{Trait 2} + E --> I[Properties] + G --> K[Properties] ``` -In this example, the `kafka` trait includes the `clientId` property for Kafka bindings. - ## Applying Traits to Operations Once a trait is defined, you can apply it to an operation using the `$ref` keyword in the `traits` section of the operation. The `$ref` value should point to the path of the trait within the `components` section. @@ -60,14 +43,11 @@ tags: - name: user - name: signup - name: register -bindings: - amqp: - ack: false traits: - $ref: '#/components/operationTraits/kafka' ``` -In this case, the `userSignup` operation in the `userSignup` channel applies the `kafka` trait, which includes the `clientId` property for Kafka bindings. +In this case, the `userSignup` operation in the `userSignup` channel applies the `kafka` trait. ## Applying Traits to Messages @@ -75,23 +55,13 @@ Traits can also be applied to `message` objects in the messages section of the A ```mermaid graph TD - A[messages] - B[myMessage] - C[traits] - D[$ref] - E[payload] - F[type: object] - G[properties] - H[message] - I[type: string] - A --> B - B --> C - C --> D - B --> E - E --> F - F --> G - G --> H - H --> I + subgraph AsyncAPI Document + traitsSection[traits] + messagesSection[messages] + end + + traitsSection --> messageObject["$ref"] + messageObject --> messagesSection ``` For example, let's say we have a trait named commonHeaders defined in messageTraits: @@ -101,84 +71,35 @@ components: messageTraits: commonHeaders: headers: - - name: Content-Type - type: string + type: object + properties: + Content-Type: + type: integer ``` To apply this trait to a message object, you can do: ```yml -channels: - userSignup: - publish: - message: - $ref: '#/components/messages/commonMessage' - traits: - - $ref: '#/components/messageTraits/commonHeaders' +traits: + - $ref: '#/components/messageTraits/commonHeaders' ``` -In this example, the `commonHeaders` trait, which includes a `Content-Type` header, is applied to the `commonMessage` within the `userSignup` operation. +In this example, the `commonHeaders` trait, which includes a `Content-Type` header, is applied to the `commonMessage`. -## Trait Merging and Overriding +## Trait Merging -Traits in AsyncAPI are merged into the message object using the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) protocol, which means that traits are merged into the operation or message object, and any conflicting properties will be overridden based on the order of evaluation. +Traits in AsyncAPI are merged into the message object using the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) protocol, which means that traits are merged into the operation or message object. ```mermaid graph TD - A[channels] - B[userSignup] - C[publish] - D[operationId] - E[bindings] - F[kafka] - G[clientId] - H[traits] - I[$ref] - A --> B + A[Traits] + B[Operation/Message] + C[Trait Merging] + + subgraph JSON Merge Patch + C + end + + A --> C B --> C - C --> D - C --> E - E --> F - F --> G - C --> H - H --> I - ``` - -For example, let's consider the following trait and operation: - -```yml -components: - operationTraits: - kafka: - bindings: - kafka: - clientId: my-app-id - groupId: default-group - -channels: - userSignup: - publish: - operationId: userSignup - traits: - - $ref: '#/components/operationTraits/kafka' - bindings: - kafka: - groupId: custom-group -``` - -In this case, the operation applies the `kafka` trait, which provides the default `clientId` and `groupId` properties. However, in the operation itself, the `groupId` property is overridden with a custom value. The final result would be: - -```yml -channels: - userSignup: - publish: - operationId: userSignup - bindings: - kafka: - clientId: my-custom-app-id # this will override the clientId defined in trait - traits: - - $ref: '#/components/operationTraits/kafka' -``` - -As demonstrated, the `groupId` property defined in the operation overrides the value defined in the trait. From 4bf534bbd6fbe42e3cd4ef66b67f0ee19f92ee81 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Thu, 10 Aug 2023 15:28:46 +0600 Subject: [PATCH 3/6] fix typo --- pages/docs/concepts/asyncapi-document/reusing-traits.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/reusing-traits.md b/pages/docs/concepts/asyncapi-document/reusing-traits.md index c095284672a..6c5be07813d 100644 --- a/pages/docs/concepts/asyncapi-document/reusing-traits.md +++ b/pages/docs/concepts/asyncapi-document/reusing-traits.md @@ -3,11 +3,11 @@ title: Reusing Traits weight: 200 --- -Traits are a powerful way to define a group of properties that can be reused across multiple message objects within the specification. Reusing traits promotes code maintainability, reduces duplication, and makes your AsyncAPI documents cleaner and easier to manage. +Traits are a powerful way to define properties that can be reused across multiple message objects within the specification. Reusing traits promotes code maintainability, reduces duplication, and makes your AsyncAPI documents cleaner and easier to manage. ## Defining Traits -Traits are defined under the `components` section of your AsyncAPI document, within `operationTraits`or `messageTraits`, depending on whether you want to apply them to operations or messages, respectively. Each trait is given a unique name and contains the properties that will be applied. +Traits are defined under the `components` section of your AsyncAPI document, within `operationTraits` or `messageTraits`, depending on whether you want to apply them to operations or messages, respectively. Each trait is given a unique name and contains the properties that will be applied. ```mermaid graph TD @@ -64,7 +64,7 @@ graph TD messageObject --> messagesSection ``` -For example, let's say we have a trait named commonHeaders defined in messageTraits: +For example, let's say we have a trait named `commonHeaders` defined in messageTraits: ```yml components: From 9b90066ce2cd9bd8c1c8d475f03bc98555fa1f2b Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 5 Sep 2023 10:47:33 +0600 Subject: [PATCH 4/6] editorial fix --- .../concepts/asyncapi-document/reusing-traits.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/reusing-traits.md b/pages/docs/concepts/asyncapi-document/reusing-traits.md index 6c5be07813d..fd20b7164f7 100644 --- a/pages/docs/concepts/asyncapi-document/reusing-traits.md +++ b/pages/docs/concepts/asyncapi-document/reusing-traits.md @@ -5,7 +5,7 @@ weight: 200 Traits are a powerful way to define properties that can be reused across multiple message objects within the specification. Reusing traits promotes code maintainability, reduces duplication, and makes your AsyncAPI documents cleaner and easier to manage. -## Defining Traits +## Defining traits Traits are defined under the `components` section of your AsyncAPI document, within `operationTraits` or `messageTraits`, depending on whether you want to apply them to operations or messages, respectively. Each trait is given a unique name and contains the properties that will be applied. @@ -20,7 +20,7 @@ graph TD G --> K[Properties] ``` -## Applying Traits to Operations +## Applying traits to operations Once a trait is defined, you can apply it to an operation using the `$ref` keyword in the `traits` section of the operation. The `$ref` value should point to the path of the trait within the `components` section. @@ -47,9 +47,9 @@ traits: - $ref: '#/components/operationTraits/kafka' ``` -In this case, the `userSignup` operation in the `userSignup` channel applies the `kafka` trait. +In this document, the `userSignup` operation in the `userSignup` channel applies the `kafka` trait. -## Applying Traits to Messages +## Applying traits to messages Traits can also be applied to `message` objects in the messages section of the AsyncAPI document. This is done using the `$ref` keyword within the `traits` section of the message object. @@ -64,7 +64,7 @@ graph TD messageObject --> messagesSection ``` -For example, let's say we have a trait named `commonHeaders` defined in messageTraits: +For example, let's say we have a trait named `commonHeaders` defined in `messageTraits`: ```yml components: @@ -77,16 +77,16 @@ components: type: integer ``` -To apply this trait to a message object, you can do: +To apply the above trait to a message object, you can do: ```yml traits: - $ref: '#/components/messageTraits/commonHeaders' ``` -In this example, the `commonHeaders` trait, which includes a `Content-Type` header, is applied to the `commonMessage`. +In this document, the `commonHeaders` trait, which includes a `Content-Type` header, is applied to the `commonMessage`. -## Trait Merging +## Trait merging Traits in AsyncAPI are merged into the message object using the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) protocol, which means that traits are merged into the operation or message object. From 7b6e5ee65dd2f3ec2cc940f984c7f7a9c21e2054 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 19 Sep 2023 20:56:48 +0600 Subject: [PATCH 5/6] small fix --- .../docs/concepts/asyncapi-document/reusing-traits.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/reusing-traits.md b/pages/docs/concepts/asyncapi-document/reusing-traits.md index fd20b7164f7..96bdda45d66 100644 --- a/pages/docs/concepts/asyncapi-document/reusing-traits.md +++ b/pages/docs/concepts/asyncapi-document/reusing-traits.md @@ -18,6 +18,9 @@ graph TD D --> G{Trait 2} E --> I[Properties] G --> K[Properties] + + style C fill:#47BCEE,stroke:#47BCEE; + style D fill:#47BCEE,stroke:#47BCEE; ``` ## Applying traits to operations @@ -31,6 +34,8 @@ graph LR C[$ref of kafka trait] A-->B B-->C + + style B fill:#47BCEE,stroke:#47BCEE; ``` Here's applying the `kafka` trait to an operation: @@ -51,7 +56,7 @@ In this document, the `userSignup` operation in the `userSignup` channel applies ## Applying traits to messages -Traits can also be applied to `message` objects in the messages section of the AsyncAPI document. This is done using the `$ref` keyword within the `traits` section of the message object. +Traits can also be applied to `message` objects in the messages section of the AsyncAPI document, which is is done using the `$ref` keyword within the `traits` section of the message object. ```mermaid graph TD @@ -62,6 +67,8 @@ graph TD traitsSection --> messageObject["$ref"] messageObject --> messagesSection + + style traitsSection fill:#47BCEE,stroke:#47BCEE; ``` For example, let's say we have a trait named `commonHeaders` defined in `messageTraits`: @@ -102,4 +109,6 @@ graph TD A --> C B --> C + + style C fill:#47BCEE,stroke:#47BCEE; ``` From 77224b50242aaa626bc97c0606f43113c3815669 Mon Sep 17 00:00:00 2001 From: Mahfuza Humayra Mohona Date: Tue, 7 Nov 2023 06:33:32 +0600 Subject: [PATCH 6/6] update --- ...and-operations-reusability-with-traits.md} | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) rename pages/docs/concepts/asyncapi-document/{reusing-traits.md => messages-and-operations-reusability-with-traits.md} (76%) diff --git a/pages/docs/concepts/asyncapi-document/reusing-traits.md b/pages/docs/concepts/asyncapi-document/messages-and-operations-reusability-with-traits.md similarity index 76% rename from pages/docs/concepts/asyncapi-document/reusing-traits.md rename to pages/docs/concepts/asyncapi-document/messages-and-operations-reusability-with-traits.md index 96bdda45d66..7e6c3cbe925 100644 --- a/pages/docs/concepts/asyncapi-document/reusing-traits.md +++ b/pages/docs/concepts/asyncapi-document/messages-and-operations-reusability-with-traits.md @@ -1,9 +1,9 @@ --- -title: Reusing Traits +title: Messages and Operations reusability with Traits weight: 200 --- -Traits are a powerful way to define properties that can be reused across multiple message objects within the specification. Reusing traits promotes code maintainability, reduces duplication, and makes your AsyncAPI documents cleaner and easier to manage. +Traits allows to define properties that can be reused across multiple message and operations within the specification. Reusing traits promotes code maintainability, reduces duplication, and makes your AsyncAPI documents cleaner and easier to manage. ## Defining traits @@ -23,6 +23,26 @@ graph TD style D fill:#47BCEE,stroke:#47BCEE; ``` +Here is an AsyncAPI document wehre an object like the following: + +```yaml +description: Example description. +traits: + - name: UserSignup + description: Trait description. + - tags: + - name: user +``` + +The document will look like the following after applying traits: + +```yaml +name: UserSignup +description: Example description. +tags: + - name: user +``` + ## Applying traits to operations Once a trait is defined, you can apply it to an operation using the `$ref` keyword in the `traits` section of the operation. The `$ref` value should point to the path of the trait within the `components` section. @@ -95,7 +115,7 @@ In this document, the `commonHeaders` trait, which includes a `Content-Type` hea ## Trait merging -Traits in AsyncAPI are merged into the message object using the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) protocol, which means that traits are merged into the operation or message object. +Traits in AsyncAPI are merged into the message object in the same order they are defined and traits are merged into the operation or message object. ```mermaid graph TD