From cf3a4502d1673a4acbbd9efd231a07aa4ced8770 Mon Sep 17 00:00:00 2001 From: Ram Shukla Date: Tue, 18 Feb 2025 20:00:29 +0530 Subject: [PATCH] Fix docs consistency in AsyncAPI documentation Fixes #3385 Make AsyncAPI documentation more consistent by standardizing formatting and word usage. * **Application.md** - Change "micro-service" to "microservice". * **Adding-messages.md** - Capitalize "components" to "Components". * **Adding-operations.md** - Capitalize "operations" to "Operations". * **Define-payload.md** - Remove unnecessary blank lines. * **Extending-specification.md** - Capitalize "Specification extensions" to "Specification Extensions". * **Reusability-with-traits.md** - Capitalize "traits" to "Traits". --- markdown/docs/concepts/application.md | 4 ++-- .../docs/concepts/asyncapi-document/adding-messages.md | 4 ++-- .../concepts/asyncapi-document/adding-operations.md | 10 +++++----- .../docs/concepts/asyncapi-document/define-payload.md | 2 -- .../asyncapi-document/extending-specification.md | 2 +- .../asyncapi-document/reusability-with-traits.md | 2 +- 6 files changed, 11 insertions(+), 13 deletions(-) diff --git a/markdown/docs/concepts/application.md b/markdown/docs/concepts/application.md index 63bc5d75757e..b60a77135d52 100644 --- a/markdown/docs/concepts/application.md +++ b/markdown/docs/concepts/application.md @@ -7,7 +7,7 @@ weight: 23 ## What is an application? An _application_ is a computer program or a group of them. -An application can be a micro-service, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. Users can create applications using various programming languages that support the chosen protocols. +An application can be a microservice, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. Users can create applications using various programming languages that support the chosen protocols. ## Why do we need applications? In Event-Driven Architecture (EDA), an application can either be a producer, a consumer, or both. Additionally, if an application wants to connect and exchange messages with the server, it must adhere to the protocols supported by the server. @@ -21,4 +21,4 @@ flowchart TD D --> F[CONSUMER application] ``` -The diagram above illustrates a message transmission between a Producer application and a Consumer application through a channel. \ No newline at end of file +The diagram above illustrates a message transmission between a Producer application and a Consumer application through a channel. diff --git a/markdown/docs/concepts/asyncapi-document/adding-messages.md b/markdown/docs/concepts/asyncapi-document/adding-messages.md index 9f81a798fdbe..a2e0aa706269 100644 --- a/markdown/docs/concepts/asyncapi-document/adding-messages.md +++ b/markdown/docs/concepts/asyncapi-document/adding-messages.md @@ -7,9 +7,9 @@ In an AsyncAPI document, adding [messages](/docs/reference/specification/v3.0.0# ## Add messages -In an AsyncAPI document, you define message definitions under channels. However, the best practice is to first define these messages under the 'components' section as reusable definitions. That way, you can reference them easily from a channel. +In an AsyncAPI document, you define message definitions under channels. However, the best practice is to first define these messages under the 'Components' section as reusable definitions. That way, you can reference them easily from a channel. -Here is a diagram showing some channel fields and the relation between channel messages and components messages: +Here is a diagram showing some channel fields and the relation between channel messages and Components messages: ```mermaid graph LR diff --git a/markdown/docs/concepts/asyncapi-document/adding-operations.md b/markdown/docs/concepts/asyncapi-document/adding-operations.md index 964e8cef18fd..6dab36eacd2c 100644 --- a/markdown/docs/concepts/asyncapi-document/adding-operations.md +++ b/markdown/docs/concepts/asyncapi-document/adding-operations.md @@ -3,15 +3,15 @@ title: Adding operations weight: 90 --- -In a messaging system, 'operations' are how messages are sent and received between participants or components. In AsyncAPI, understanding operations helps you see how the system sends asynchronous messages back and forth without waiting for responses. They serve as a vital tool, aiding users in comprehending the range of tasks and functionalities that the API is capable of performing. +In a messaging system, 'Operations' are how messages are sent and received between participants or components. In AsyncAPI, understanding Operations helps you see how the system sends asynchronous messages back and forth without waiting for responses. They serve as a vital tool, aiding users in comprehending the range of tasks and functionalities that the API is capable of performing. -In an AsyncAPI document, operations describe your application's behaviors and capabilities by exchanging messages through channels configured in the AsyncAPI document. An `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. +In an AsyncAPI document, Operations describe your application's behaviors and capabilities by exchanging messages through channels configured in the AsyncAPI document. An `Operation` represents a particular action or interaction that can be performed. The purpose of Operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. ## Defining operations -Operations can be defined as an independent object in the AsyncAPI document. More information about each field name that is used to define operations can be found [in the reference documentation of the specification](/docs/reference/specification/v3.0.0#operationObject). +Operations can be defined as an independent object in the AsyncAPI document. More information about each field name that is used to define Operations can be found [in the reference documentation of the specification](/docs/reference/specification/v3.0.0#operationObject). -The following diagram declares the field names that are frequently used to define operations in an AsyncAPI document: +The following diagram declares the field names that are frequently used to define Operations in an AsyncAPI document: ```mermaid flowchart LR @@ -33,7 +33,7 @@ flowchart LR ## Adding operations -In the AsyncAPI document, 'operations' are distinct fields located at the root level of the document, alongside 'channels' and other key fields. +In the AsyncAPI document, 'Operations' are distinct fields located at the root level of the document, alongside 'channels' and other key fields. Operations must specify on what channel they are performed by referencing the `channel` with `$ref`. For example: ``` diff --git a/markdown/docs/concepts/asyncapi-document/define-payload.md b/markdown/docs/concepts/asyncapi-document/define-payload.md index 370cbf9652c9..7755cba0515f 100644 --- a/markdown/docs/concepts/asyncapi-document/define-payload.md +++ b/markdown/docs/concepts/asyncapi-document/define-payload.md @@ -151,5 +151,3 @@ The process is more complex for Protobuf schemas, as their Protocol Buffers are optional string label = 3; } ``` - - diff --git a/markdown/docs/concepts/asyncapi-document/extending-specification.md b/markdown/docs/concepts/asyncapi-document/extending-specification.md index b24fbf51a8cf..fb44ccd38156 100644 --- a/markdown/docs/concepts/asyncapi-document/extending-specification.md +++ b/markdown/docs/concepts/asyncapi-document/extending-specification.md @@ -5,7 +5,7 @@ weight: 240 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 +## Specification Extensions 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. diff --git a/markdown/docs/concepts/asyncapi-document/reusability-with-traits.md b/markdown/docs/concepts/asyncapi-document/reusability-with-traits.md index edab24162061..d2b35efa95d9 100644 --- a/markdown/docs/concepts/asyncapi-document/reusability-with-traits.md +++ b/markdown/docs/concepts/asyncapi-document/reusability-with-traits.md @@ -1,5 +1,5 @@ --- -title: Reusability with traits +title: Reusability with Traits weight: 200 ---