From ee2f9fa40bddba0a1725e9ad3308194ce92b2daf Mon Sep 17 00:00:00 2001 From: Mahfuza Humayra Mohona Date: Fri, 8 Dec 2023 16:43:21 +0600 Subject: [PATCH 1/3] add extend specification --- .../extending-specification.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/extending-specification.md diff --git a/pages/docs/concepts/asyncapi-document/extending-specification.md b/pages/docs/concepts/asyncapi-document/extending-specification.md new file mode 100644 index 00000000000..f2bd8f7cae3 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/extending-specification.md @@ -0,0 +1,73 @@ +--- +title: Extending Specification +weight: 240 +--- + +Extending the AsyncAPI specification is a technique that allows developers to include domain-specific or use case specific information not supported by the base specification. This extension capability provides customization, enabling APIs to accommodate unique details that would not otherwise fit within the confines of the standard AsyncAPI specification. + +## Specification extensions + +The AsyncAPI Specification allows the addition of custom properties through patterned fields prefixed with `x-`. This helps you create unique things without causing problems with future updates. + +The `x-` prefix is used to define custom properties. These properties are user-defined and won't conflict with future specification versions because any property starting with `x-` is reserved for user definitions. + +Here is a diagram explaining specification extensions: + +```mermaid +flowchart TD + subgraph "AsyncAPI Specification" + A[Specification] --> B[Custom Properties] + end + style B fill:#47BCEE,stroke:#47BCEE; + subgraph "Custom Properties" + B --> C[Patterned fields prefixed with x-] + C --> D[User-defined properties] + C --> E[Reserved for user definitions] + end +``` + +The above diagram explains how AsyncAPI specification uses `x-` prefixed fields for custom properties. + +Here is an example of how to extend the AsyncAPI specification: + +```yml +asyncapi: 3.0.0 +info: + title: Cool Example + version: 0.1.0 +channels: + userSignedUp: + address: user/signedup + messages: + userSignedUp: + description: An event describing that a user just signed up. + x-custom-property: Custom Value +``` + +In the above document, under the `user/signedup` channel, a custom property `x-custom-property` is added. The value assigned to this property is `Custom Value`. + + +All available tooling might not support AsyncAPI extensions. The tooling can be extended to understand and handle the added data, especially if the tools are internal or open source. + + +## Extending unsupported features + +When facing a case where the AsyncAPI specification does not support the required feature, that functionality can be extended using these extensions. If the extended part also benefits other developers, you could contribute to the AsyncAPI specification. This contribution can be made by [creating an issue](https://github.com/asyncapi/spec) on the AsyncAPI GitHub repository. Please get familiar with [contribution guide](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md) before making an contribution. + +Here is a diagram showing details about extending extending unsupported features: + +```mermaid + graph TD + A[Encounter Unsupported Feature] + B[Extend using Extensions] + C[Beneficial to Others?] + D[Contribute to Specification] + + style A fill:#47BCEE,stroke:#47BCEE; + + A --> B + B --> C + C -->|Yes| D +``` + +This diagram shows the process of extending AsyncAPI specifications when unsupported features are encountered, with an option to contribute to the specification if it benefits others. From 3ee0719dd40bc7b1f92dd0573dc42706308e3e7c Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 13 Dec 2023 21:26:23 +0100 Subject: [PATCH 2/3] Update extending-specification.md --- .../extending-specification.md | 49 ++----------------- 1 file changed, 5 insertions(+), 44 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/extending-specification.md b/pages/docs/concepts/asyncapi-document/extending-specification.md index f2bd8f7cae3..d8c25a527b4 100644 --- a/pages/docs/concepts/asyncapi-document/extending-specification.md +++ b/pages/docs/concepts/asyncapi-document/extending-specification.md @@ -3,7 +3,7 @@ title: Extending Specification weight: 240 --- -Extending the AsyncAPI specification is a technique that allows developers to include domain-specific or use case specific information not supported by the base specification. This extension capability provides customization, enabling APIs to accommodate unique details that would not otherwise fit within the confines of the standard AsyncAPI specification. +Extending the AsyncAPI specification is a technique that allows you to include domain-specific or use case specific information not supported by the base specification or protocol-specific bindings. This extension capability provides customization, enabling APIs to accommodate unique details that would not otherwise fit within the confines of the standard AsyncAPI specification. ## Specification extensions @@ -11,40 +11,19 @@ The AsyncAPI Specification allows the addition of custom properties through patt The `x-` prefix is used to define custom properties. These properties are user-defined and won't conflict with future specification versions because any property starting with `x-` is reserved for user definitions. -Here is a diagram explaining specification extensions: +Extensions can be use in any part of AsyncAPI document. -```mermaid -flowchart TD - subgraph "AsyncAPI Specification" - A[Specification] --> B[Custom Properties] - end - style B fill:#47BCEE,stroke:#47BCEE; - subgraph "Custom Properties" - B --> C[Patterned fields prefixed with x-] - C --> D[User-defined properties] - C --> E[Reserved for user definitions] - end -``` - -The above diagram explains how AsyncAPI specification uses `x-` prefixed fields for custom properties. - -Here is an example of how to extend the AsyncAPI specification: +Here is an example of how to extend the AsyncAPI document with custom property: ```yml asyncapi: 3.0.0 info: title: Cool Example version: 0.1.0 -channels: - userSignedUp: - address: user/signedup - messages: - userSignedUp: - description: An event describing that a user just signed up. - x-custom-property: Custom Value + x-linkedin: '/company/asyncapi' ``` -In the above document, under the `user/signedup` channel, a custom property `x-custom-property` is added. The value assigned to this property is `Custom Value`. +In the above document, you can see an `info` object extended with custom information about LinkedIn account of company owning the application. Custom information is represented by custom property called `x-linkedin`. All available tooling might not support AsyncAPI extensions. The tooling can be extended to understand and handle the added data, especially if the tools are internal or open source. @@ -53,21 +32,3 @@ All available tooling might not support AsyncAPI extensions. The tooling can be ## Extending unsupported features When facing a case where the AsyncAPI specification does not support the required feature, that functionality can be extended using these extensions. If the extended part also benefits other developers, you could contribute to the AsyncAPI specification. This contribution can be made by [creating an issue](https://github.com/asyncapi/spec) on the AsyncAPI GitHub repository. Please get familiar with [contribution guide](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md) before making an contribution. - -Here is a diagram showing details about extending extending unsupported features: - -```mermaid - graph TD - A[Encounter Unsupported Feature] - B[Extend using Extensions] - C[Beneficial to Others?] - D[Contribute to Specification] - - style A fill:#47BCEE,stroke:#47BCEE; - - A --> B - B --> C - C -->|Yes| D -``` - -This diagram shows the process of extending AsyncAPI specifications when unsupported features are encountered, with an option to contribute to the specification if it benefits others. From 97a1116c55d158b8e965b84e5956f0f4afef7bab Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 15 Dec 2023 20:12:08 -0800 Subject: [PATCH 3/3] tw editorial fixes --- .../asyncapi-document/extending-specification.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/extending-specification.md b/pages/docs/concepts/asyncapi-document/extending-specification.md index d8c25a527b4..b24fbf51a8c 100644 --- a/pages/docs/concepts/asyncapi-document/extending-specification.md +++ b/pages/docs/concepts/asyncapi-document/extending-specification.md @@ -1,19 +1,19 @@ --- -title: Extending Specification +title: Extending specification weight: 240 --- -Extending the AsyncAPI specification is a technique that allows you to include domain-specific or use case specific information not supported by the base specification or protocol-specific bindings. This extension capability provides customization, enabling APIs to accommodate unique details that would not otherwise fit within the confines of the standard AsyncAPI specification. +Extending the AsyncAPI specification allows you to include specific information for your domain or use case that's not currently supported by the original specification or the protocol bindings. Extension capability allows for customization, making it possible to integrate unique aspects into APIs that the standard AsyncAPI specification doesn't normally accommodate. ## Specification extensions -The AsyncAPI Specification allows the addition of custom properties through patterned fields prefixed with `x-`. This helps you create unique things without causing problems with future updates. +The AsyncAPI Specification allows the addition of custom properties through patterned fields prefixed with an `x-`. That way, you can create unique things without causing problems in future updates. The `x-` prefix is used to define custom properties. These properties are user-defined and won't conflict with future specification versions because any property starting with `x-` is reserved for user definitions. -Extensions can be use in any part of AsyncAPI document. +Extensions can be used in any part of the AsyncAPI document. -Here is an example of how to extend the AsyncAPI document with custom property: +Here is an example of how to extend the AsyncAPI document with a custom property: ```yml asyncapi: 3.0.0 @@ -23,12 +23,12 @@ info: x-linkedin: '/company/asyncapi' ``` -In the above document, you can see an `info` object extended with custom information about LinkedIn account of company owning the application. Custom information is represented by custom property called `x-linkedin`. +The above document shows an `info` object extended with custom information about a company's LinkedIn account that owns the application. Custom information is represented via a custom property called `x-linkedin`. -All available tooling might not support AsyncAPI extensions. The tooling can be extended to understand and handle the added data, especially if the tools are internal or open source. +AsyncAPI tools might not support AsyncAPI extensions. Our tools can be extended to understand and handle the added data, especially if the tools are internal or open source. ## Extending unsupported features -When facing a case where the AsyncAPI specification does not support the required feature, that functionality can be extended using these extensions. If the extended part also benefits other developers, you could contribute to the AsyncAPI specification. This contribution can be made by [creating an issue](https://github.com/asyncapi/spec) on the AsyncAPI GitHub repository. Please get familiar with [contribution guide](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md) before making an contribution. +If you need a feature not covered by the AsyncAPI specification, you can create an extension for it. Should this extension be useful to others, consider contributing it back to the AsyncAPI community. You can do this by [opening a spec issue](https://github.com/asyncapi/spec) in the AsyncAPI GitHub repository. Before contributing, review the [AsyncAPI contribution guidelines](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md).