diff --git a/markdown/docs/concepts/asyncapi-document/index.md b/markdown/docs/concepts/asyncapi-document/index.md index 9419ff90ff8..f3ea148e8e0 100644 --- a/markdown/docs/concepts/asyncapi-document/index.md +++ b/markdown/docs/concepts/asyncapi-document/index.md @@ -3,9 +3,9 @@ title: 'Introduction' weight: 50 --- -The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an application’s API. While the document may reference other files for additional details or shared fields, it usually serves as a single, primary document that encapsulates the API description. +The [AsyncAPI specification](/docs/reference/specification/latest) defines fields for describing an application's API in an *AsyncAPI document*. While the document may reference other files for details or shared fields, it typically serves as a single, primary document that encapsulates the API description. -Furthermore, the AsyncAPI document acts as a communication contract between receivers and senders within an event-driven system. It specifies the payload content necessary for a service to send a message and provides clear guidance to the receiver about the message's properties. +The AsyncAPI document is a communication contract between senders and receivers within an event-driven system. It specifies the payload content required for a service to send a message and provides the receiver with guidance about the message's properties. ```yaml asyncapi: 3.0.0 @@ -37,5 +37,5 @@ operations: ``` -Depending on the implemented protocol (such as MQTT, AMQP, Kafka, etc.), you may have additional fields in your AsyncAPI document. For example, for configuring Kafka bindings. +Depending on the protocol (such as MQTT, AMQP, Kafka), your AsyncAPI document may have additional fields. For example, for [configuring Kafka bindings](https://github.com/asyncapi/bindings/tree/master/kafka). diff --git a/markdown/docs/concepts/asyncapi-document/structure.md b/markdown/docs/concepts/asyncapi-document/structure.md index 9b3d9fb9be2..98e30ac8d8e 100644 --- a/markdown/docs/concepts/asyncapi-document/structure.md +++ b/markdown/docs/concepts/asyncapi-document/structure.md @@ -3,11 +3,11 @@ title: AsyncAPI document structure weight: 60 --- -The structure of an AsyncAPI document is defined in a specific format and must follow the [AsyncAPI specification](/docs/reference/specification/latest). The structure of an AsyncAPI document has certain fields that you need to follow, although not all of them are mandatory. +An AsyncAPI document structure must follow a specific format defined by the [AsyncAPI specification][asyncapi-spec]. It has mandatory and optional fields. ## Root elements -Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements collectively define the metadata, channels, components, and more of an AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. +Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements define metadata, channels, components, and more. ```mermaid graph @@ -27,48 +27,23 @@ A --> F ### `info` field -The `info` field in an API document offers crucial metadata, including the API's title, version, description, contact details, and license. This field provides a comprehensive overview of the API, aiding developers, architects, and other stakeholders in quickly grasping its purpose and capabilities. As a mandatory element of the AsyncAPI specification, the `info` field often serves as the initial reference point for users navigating the API documentation. - -The `info` field encompasses various fields such as: +The [`info` field][info-object] is a mandatory element of the AsyncAPI specification that serves as the initial reference point for users navigating the API documentation and helping developers, architects, and other stakeholders quickly grasp the API's purpose and capabilities. This field contains essential metadata, including: - `title`: API title. - `version`: API version. -- `description`: Brief description describing the API's purpose and features. +- `description`: Brief description of the API's purpose and features. - `termsOfService`: URL or document specifying the API's terms of service. - `contact`: Contact information of the API's owner or maintainer (name, email, and URL). - `license`: API's license information, including name and URL. -- `tags`: Tags for categorizing and organizing API documentation. Also used for grouping applications logically. -- `externalDocs`: Links to additional, external documentation related to the API. - -Here's a visual representation of the `info` field and its properties: -```mermaid -graph LR - B(info) - C(title) - D(version) - E(description) - F(termsOfService) - G(contact) - J(license) - M(tags) - P(externalDocs) - - B --> C - B --> D - B --> E - B --> F - B --> G - B --> J - B --> M - B --> P -``` +- `tags`: A list of keywords to organize and categorize API documentation. They are also used to group applications logically. +- `externalDocs`: Links to additional, external documentation related to the API. Below is an example of the `info` field: ```yaml info: title: My Event-Driven API version: 1.0.0 - description: This API provides real-time event streaming capabilities. + description: This API provides real-time event streaming capabilities termsOfService: https://example.com/terms-of-service contact: name: Rohit @@ -88,53 +63,22 @@ info: ### `servers` field -The `servers` field allows you to detail a range of servers, outlining the network endpoints or message brokers to which applications can connect. That field includes vital connection information like protocol, host, port, and other options, facilitating connectivity across various environments such as production, staging, or development. +The [`servers` field][server-object] details various servers, including network endpoints or message brokers to which applications can connect. This field includes connection information like protocol, host, port, and other options, enabling connectivity across different environments like production, staging, or development. -Some of the fields of individual `servers` field are: +The individual `servers` field contains the following properties: -- `host`: The server host name. It may include the port. -- `protocol`: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). -- `protocolVersion`: The version of the protocol used for the connection. +- `host`: The server hostname. It may include the port. +- `protocol`: The protocol or messaging protocol that is used by the server (for example, AMQP, MQTT, WebSocket). +- `protocolVersion`: The protocol version used for the connection. - `pathname`: The path to a resource in the host. -- `description`: An optional string describing the server. +- `description`: A string describing the server. - `title`: A human-friendly title for the server. -- `summary`: A summary of the server. -- `security`: A declaration of which security schemes can be used with this server. -- `tags`: A list of tags for logical grouping and categorization of servers. +- `summary`: A brief overview of the server. +- `security`: A declaration of security schemes supported by the server. +- `tags`: a list of keywords to logically group and categorize servers. - `externalDocs`: Additional external documentation for this server. - `bindings`: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. -Here's a visual representation of the `server` object and its properties: -```mermaid -graph LR - A[server] - B(host) - C(pathname) - D(protocol) - E(protocolVersion) - F(description) - G(title) - H(summary) - I(variables) - J(security) - K(tags) - L(externalDocs) - M(bindings) - - A --> B - A --> C - A --> D - A --> E - A --> F - A --> G - A --> H - A --> I - A --> J - A --> K - A --> L - A --> M -``` - Below is an example of the `servers` field with multiple servers: ```yaml servers: @@ -142,8 +86,8 @@ servers: host: rabbitmq.in.mycompany.com:5672 pathname: /v1 protocol: amqp - protocolVersion: "1.0" - description: Production RabbitMQ broker (uses the `production` vhost). + protocolVersion: 1.0 + description: Production RabbitMQ broker (uses the `production` vhost) title: Production Server summary: Production environment server security: @@ -163,14 +107,14 @@ servers: host: rabbitmq.in.mycompany.com:5672 pathname: /v1 protocol: amqp - protocolVersion: "1.0" - description: Staging RabbitMQ broker (uses the `staging` vhost). + protocolVersion: 1.0 + description: Staging RabbitMQ broker (uses the `staging` vhost) title: Staging Server summary: Staging environment server security: - type: apiKey in: user - description: Provide your API key as the user and leave the password empty. + description: Provide your API key as the user and leave the password empty tags: - name: staging description: Staging environment @@ -185,53 +129,28 @@ servers: ### `channels` field -With the `channels` field, you can provide a map of different channels the application communicates with during runtime. The `channels` represent the communication pathways through which messages are exchanged. You can specify their purpose, address, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. +With the [`channels` field][channel-object], you can provide a map of channels the application communicates with during runtime. For each channel, you can specify the purpose, address, and expected message formats so that API consumers can understand the supported message-based interactions and the corresponding data models. -Key components within the `channels` field include: +The individual `channels` field contains the following properties: - `address`: A string representation of this channel's address. -- `messages`: A map of the messages that will be sent to this channel by any application at any time. +- `messages`: A map of all messages sent to this channel by any application. - `title`: A human-readable title for the channel. -- `summary`: A short yet brief summary of the channel. +- `summary`: A summary of the channel. - `description`: A description of the channel, providing additional context and details of the message. -- `servers`: An array of `$ref` pointers to the definition of the servers in which this channel is available. If servers are absent or empty, this channel must be available on all the servers defined in the `servers` field. +- `servers`: An array of `$ref` pointers to the server definitions for this channel. If servers are absent or empty, this channel must be available on all servers defined in the `servers` field. - `parameters`: A map of the parameters included in the channel address. -- `tags`: A list of tags for logical grouping of channels. +- `tags`: a list of keywords to logically group channels. - `externalDocs`: Additional external documentation for this channel. - `bindings`: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. -Here's a visual representation of the `channels` field and its properties: -```mermaid -graph LR - A[channel] - B(address) - C(title) - D(description) - E(messages) - H(parameters) - J(servers) - M(bindings) - P(tags) - R(externalDocs) - - A -->B - A --> C - A --> D - A --> E - A --> H - A --> J - A --> M - A --> P - A --> R -``` - -Below is an example of of the `channels` field with one channel: +Below is an example of the `channels` field with one channel: ```yaml channels: user: address: 'users.{userId}' title: Users channel - description: This channel is used to exchange messages about user events. + description: This channel is used to exchange messages about user events messages: userSignedUp: $ref: '#/components/messages/userSignedUp' @@ -251,69 +170,36 @@ channels: - name: user description: User-related messages externalDocs: - description: 'Find more info here' - url: 'https://example.com' + description: Find more info here + url: https://example.com ``` ### `operations` field -The `operations` field is used to comprehensively outline the various operations performed by the application. It offers a clear, structured description, detailing whether the application sends or receives messages and the specific purpose of each operation. +The [`operations` field][operation-object] specifies operations the application can perform. It offers a clear and structured description detailing whether the application sends or receives messages and the specific purpose of each operation. -Key components within the `operations` field include: +The individual `operations` field contains the following properties: -- `action`: Use `send` type when it's expected that the application will send a message to the given channel, and `receive` type when the application should expect to receive messages from the given channel. -- `channel`: A `$ref` pointer to the definition of the channel in which this operation is performed. +- `action`: Use `send` when the application expects to send a message to a channel and `receive` when it expects to receive messages from a channel. +- `channel`: A `ref` pointer to the channel definition that ensures the operation execution. - `title`: A human-friendly title for the operation. -- `summary`: A short summary of what the operation is about. -- `description`: A verbose explanation of the operation. -- `security`: A declaration of which security schemes are associated with this operation. -- `tags`: A list of tags for logical grouping and categorization of operations. +- `summary`: A brief overview of the operation. +- `description`: A detailed explanation of the operation. +- `security`: A declaration of security schemes associated with the operation. +- `tags`: a list of keywords to logically group and categorize operations. - `externalDocs`: Additional external documentation for this operation. -- `bindings` A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. -- `traits`: A list of traits to apply to the operation object. -- `messages`: A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation. -- `reply`: The definition of the reply in a reply/request operation. - -Here's a visual representation of the `operations` field and its properties: -```mermaid -graph LR - A[operation] - B(title) - C(summary) - D(description) - E(channel) - F(action) - G(security) - H(tags) - I(bindings) - J(traits) - K(messages) - L(reply) - M(address) - N(channel) - - A --> B - A --> C - A --> D - A --> E - A --> F - A --> G - A --> H - A --> I - A --> J - A --> K - A --> L - L --> M - L --> N -``` +- `bindings`: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. +- `traits`: A list of traits to apply to the operation object. +- `messages`: A list of `$ref` pointers to the supported Message Objects that this operation can process. +- `reply`: The definition of the reply in a reply/request operation. -Below is an example of of the `operations` field with one operation: +Below is an example of the `operations` field with one operation: ```yaml operations: sendUserSignUp: action: send 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/user' @@ -322,7 +208,7 @@ operations: description: The oauth security descriptions flows: clientCredentials: - tokenUrl: 'https://example.com/api/oauth/dialog' + tokenUrl: https://example.com/api/oauth/dialog availableScopes: 'subscribe:auth_revocations': Scope required for authorization revocation topic scopes: @@ -335,7 +221,7 @@ operations: amqp: ack: false traits: - - $ref: "#/components/operationTraits/kafka" + - $ref: '#/components/operationTraits/kafka' messages: - $ref: '#/components/messages/userSignedUp' reply: @@ -349,74 +235,31 @@ operations: ### `components` field -The `components` field allows for the definition of reusable structures or definitions applicable across various sections of your document. Items detailed within `components` only become part of the API when explicitly referenced by properties external to this field. Utilize it to avoid repetition and enhance the document's maintainability. - -Key components of the `components` field include: - -- `schemas`: An object to hold the reusable [Schema Object](/docs/reference/specification/latest#schemaObject). -- `servers`: An object to hold the reusable [Server Objects](/docs/reference/specification/latest#serverObject). -- `channels`: An object to hold the reusable [Channel Objects](/docs/reference/specification/latest#channelObject). -- `operations`: An object to hold the reusable [Operation Item Objects](/docs/reference/specification/latest#operationObject). -- `messages`: An object to hold the reusable [Messages Objects](/docs/reference/specification/latest#messageObject). -- `securitySchemes`: An object to hold the reusable [Security Scheme Objects](/docs/reference/specification/latest#securitySchemeObject). -- `serverVariables`: An object to hold the reusable [Server Variable Objects](/docs/reference/specification/latest#serverVariableObject). -- `parameters`: Contains reusable [Parameter Objects](/docs/reference/specification/latest#parameterObject) that can be used in various parts of the AsyncAPI document. -- `correlationIds`: An object to hold the reusable [Correlation ID Objects](/docs/reference/specification/latest#correlationIdObject). -- `replies`: An object to hold the reusable [Operation Reply Objects](/docs/reference/specification/latest#operationReplyObject). -- `replyAddresses`: An object to hold the reusable [Operation Reply Address Objects](/docs/reference/specification/latest#operationReplyAddressObject). -- `externalDocs`: An object to hold the reusable [External Documentation Objects](docs/reference/specification/latest#externalDocumentationObject). -- `tags`: An object to hold the reusable [Tag Objects](/docs/reference/specification/latest#tagObject). -- `operationTraits`: An object to hold the reusable [Operation Trait Objects](/docs/reference/specification/latest#operationTraitObject). -- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects](/docs/reference/specification/latest#messageTraitObject). -- `serverBindings`: An object to hold the reusable [Server Bindings Objects](/docs/reference/specification/latest#serverBindingsObject). -- `channelBindings`: An object to hold the reusable [Channel Bindings Objects](/docs/reference/specification/latest#channelBindingsObject). -- `operationBindings`: An object to hold the reusable [Operation Bindings Objects](/docs/reference/specification/latest#operationBindingsObject). -- `messageBindings`: An object to hold the reusable [Message Bindings Objects](/docs/reference/specification/latest#messageBindingsObject). - -Here's a visual representation of the `components` field and its properties: -```mermaid -graph LR - A[components] - B(schemas) - C(messages) - D(serverVariables) - E(replies) - F(replyAddresses) - G(servers) - H(operations) - I(securitySchemes) - J(tags) - K(operationTraits) - L(channels) - M(serverBindings) - N(channelBindings) - O(operationBindings) - R(messageBindings) - P(externalDocs) - U(parameters) - W(correlationIds) - Y(messageTraits) - - A --> B - A --> C - A --> H - A --> G - A --> D - A --> L - A --> U - A --> P - A --> I - A --> W - A --> Y - A --> K - A --> J - A --> E - A --> F - A --> M - A --> N - A --> O - A --> R -``` +The [`components` field][components-object] allows for the definition of reusable structures or definitions applicable across various sections of your document. Items detailed within `components` only become part of the API when explicitly referenced by properties external to this field. Utilize it to avoid repetition and enhance the document's maintainability. + +The `components` field lets you define reusable structures or definitions across your document. Items in `components` only become part of the API when explicitly referenced by properties outside this field, so you can use it to avoid repetition and improve maintainability. + +The `components` field contains the following properties: + +- `schemas`: An object to hold the reusable [Schema Object][schema-object]. +- `servers`: An object to hold the reusable [Server Objects][server-object]. +- `channels`: An object to hold the reusable [Channel Objects][channel-object]. +- `operations`: An object to hold the reusable [Operation Item Objects][operation-item-object]. +- `messages`: An object to hold the reusable [Messages Objects][message-object]. +- `securitySchemes`: An object to hold the reusable [Security Scheme Objects][security-scheme-object]. +- `serverVariables`: An object to hold the reusable [Server Variable Objects][server-variable-object]. +- `parameters`: Contains reusable [Parameter Objects][parameter-object] that can be used in various parts of the AsyncAPI document. +- `correlationIds`: An object to hold the reusable [Correlation ID Objects][correlation-id-object]. +- `replies`: An object to hold the reusable [Operation Reply Objects][operation-reply-object]. +- `replyAddresses`: An object to hold the reusable [Operation Reply Address Objects][operation-reply-address-object]. +- `externalDocs`: An object to hold the reusable [External Documentation Objects][external-documentation-object]. +- `tags`: An object to hold the reusable [Tag Objects][tag-object]. +- `operationTraits`: An object to hold the reusable [Operation Trait Objects][operation-trait-object]. +- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects][message-trait-object]. +- `serverBindings`: An object to hold the reusable [Server Bindings Objects][server-bindings-object]. +- `channelBindings`: An object to hold the reusable [Channel Bindings Objects][channel-bindings-object]. +- `operationBindings`: An object to hold the reusable [Operation Bindings Objects][operation-bindings-object]. +- `messageBindings`: An object to hold the reusable [Message Bindings Objects][message-bindings-object]. Here's a code example of the components object in an AsyncAPI document: ```yaml @@ -456,7 +299,7 @@ components: user: address: 'users.{userId}' title: Users channel - description: This channel is used to exchange messages about user events. + description: This channel is used to exchange messages about user events messages: userSignedUp: $ref: '#/components/messages/userSignUp' @@ -474,7 +317,7 @@ components: messages: userSignUp: - summary: Action to sign a user up. + summary: Action to sign a user up traits: - $ref: '#/components/messageTraits/commonHeaders' payload: @@ -486,7 +329,7 @@ components: parameters: userId: - description: Id of the user. + description: Id of the user correlationIds: default: @@ -522,7 +365,7 @@ components: description: The oauth security descriptions flows: clientCredentials: - tokenUrl: 'https://example.com/api/oauth/dialog' + tokenUrl: https://example.com/api/oauth/dialog availableScopes: 'subscribe:auth_revocations': Scope required for authorization revocation topic scopes: @@ -552,7 +395,7 @@ components: externalDocs: infoDocs: url: https://example.com/docs - description: 'Find more info here' + description: Find more info here serverBindings: devAmqp: @@ -577,5 +420,30 @@ components: amqp: contentEncoding: gzip messageType: 'user.signup' - bindingVersion: '0.2.0' + bindingVersion: 0.2.0 ``` + + +- [asyncapi-spec]: /docs/reference/specification/latest +- [info-object]: /docs/reference/specification/latest#infoObject +- [schema-object]: /docs/reference/specification/latest#schemaObject +- [server-object]: /docs/reference/specification/latest#serverObject +- [channel-object]: /docs/reference/specification/latest#channelObject +- [operation-object]: /docs/reference/specification/latest#operationObject +- [operation-item-object]: /docs/reference/specification/latest#operationObject +- [components-object]: /docs/reference/specification/latest#componentsObject +- [message-object]: /docs/reference/specification/latest#messageObject +- [security-scheme-object]: /docs/reference/specification/latest#securitySchemeObject +- [server-variable-object]: /docs/reference/specification/latest#serverVariableObject +- [parameter-object]: /docs/reference/specification/latest#parameterObject +- [correlation-id-object]: /docs/reference/specification/latest#correlationIdObject +- [operation-reply-object]: /docs/reference/specification/latest#operationReplyObject +- [operation-reply-address-object]: /docs/reference/specification/latest#operationReplyAddressObject +- [external-documentation-object]: docs/reference/specification/latest#externalDocumentationObject +- [tag-object]: /docs/reference/specification/latest#tagObject +- [operation-trait-object]: /docs/reference/specification/latest#operationTraitObject +- [message-trait-object]: /docs/reference/specification/latest#messageTraitObject +- [server-bindings-object]: /docs/reference/specification/latest#serverBindingsObject +- [channel-bindings-object]: /docs/reference/specification/latest#channelBindingsObject +- [operation-bindings-object]: /docs/reference/specification/latest#operationBindingsObject +- [message-bindings-object]: /docs/reference/specification/latest#messageBindingsObject