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/messages-and-operations-reusability-with-traits.md b/pages/docs/concepts/asyncapi-document/messages-and-operations-reusability-with-traits.md new file mode 100644 index 00000000000..7e6c3cbe925 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/messages-and-operations-reusability-with-traits.md @@ -0,0 +1,134 @@ +--- +title: Messages and Operations reusability with Traits +weight: 200 +--- + +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 + +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[AsyncAPI Document] --> B{Components} + B --> C[operationTraits] + B --> D[messageTraits] + C --> E{Trait 1} + D --> G{Trait 2} + E --> I[Properties] + G --> K[Properties] + + style C fill:#47BCEE,stroke:#47BCEE; + 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. + +```mermaid +graph LR + A((User Signup Operation)) + B[traits] + C[$ref of kafka trait] + A-->B + B-->C + + style B fill:#47BCEE,stroke:#47BCEE; +``` + +Here's applying the `kafka` trait to an operation: + +```yml +channel: + $ref: '#/channels/userSignup' +action: send +tags: + - name: user + - name: signup + - name: register +traits: + - $ref: '#/components/operationTraits/kafka' +``` + +In this document, the `userSignup` operation in the `userSignup` channel applies the `kafka` trait. + +## Applying traits to messages + +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 + subgraph AsyncAPI Document + traitsSection[traits] + messagesSection[messages] + end + + 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`: + +```yml +components: + messageTraits: + commonHeaders: + headers: + type: object + properties: + Content-Type: + type: integer +``` + +To apply the above trait to a message object, you can do: + +```yml +traits: + - $ref: '#/components/messageTraits/commonHeaders' +``` + +In this document, the `commonHeaders` trait, which includes a `Content-Type` header, is applied to the `commonMessage`. + +## Trait merging + +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 + A[Traits] + B[Operation/Message] + C[Trait Merging] + + subgraph JSON Merge Patch + C + end + + A --> C + B --> C + + style C fill:#47BCEE,stroke:#47BCEE; +```