From 30a8f13e086293a9e90b817a808f45915750fb6c Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Sun, 9 Jul 2023 12:35:41 +0530 Subject: [PATCH 01/22] GSoD-Initial Draft --- .../concepts/asyncapi-document/_section.md | 4 + .../concepts/asyncapi-document/structure.md | 387 ++++++++++++++++++ 2 files changed, 391 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/structure.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..05a0c710216 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -0,0 +1,4 @@ +--- +title: 'AsyncAPI Document' +weight: 50 +--- diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md new file mode 100644 index 00000000000..cd77da1770a --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -0,0 +1,387 @@ +--- +title: AsyncAPI Structure +weight: 32 +--- + + +## What's a AysncAPI Document? +An AsyncAPI document is a file written in the AsyncAPI specification format. It is a machine-readable document that describes the structure, format, and behavior of a specific asynchronous API or event-driven API. The document provides a standardized way to define the messages, topics, channels, protocols, and other components involved in the communication. + +An AsyncAPI document typically has a YAML or JSON format and contains various sections that define different aspects of the API like a structure that defines and explains what the specific API needs to do or does. + +## Root Elements +Root elements provide a overview of the API's characteristics and behavior.These root elements collectively define the structure, metadata, endpoints, channels, components and more of an AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. + +```mermaid +graph LR +A[asyncapi] +B[info] +C[servers] +D[channels] +E[components] +F[security] +G[tags] +H[externalDocs] + +A -->|1| B +A -->|2| C +A -->|3| D +A -->|4| E +A -->|5| F +A -->|6| G +A -->|7| H +``` + +### `Info` object +The `info` object in an AsyncAPI document provides essential information about the API in the form of fields such as title, version, description, contact details and license. It serves as metadata that gives consumers a high-level understanding of the API's purpose and functionality. + +The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, Info is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. + +The `info` object includes properties such as: + +- title: The title of the API. +- version: The version of the API. +- description: A brief description explaining the purpose and features of the API. +- termsOfService: The URL or document specifying the terms of service for using the API. +- contact: Contact information for the owner or maintainer of the API, including name, email, and URL. +- license: Information about the license under which the API is provided, including name and URL. + +```mermaid +graph LR +A[info] +B[title] +C[version] +D[description] +E[termsOfService] +F[contact] +G[name] +H[email] +I[url] +J[license] +K[name] +L[url] + +A -->|1| B +A -->|2| C +A -->|3| D +A -->|4| E +A -->|5| F +F -->|6| G +F -->|7| H +F -->|8| I +A -->|9| J +J -->|10| K +J -->|11| L +``` + +Below is a example of the `info` object in the AsyncAPI document: +```yaml +info: + title: My AsyncAPI Example + version: 1.0.0 + description: An example of info object + termsOfService: https://example.com/terms + contact: + name: Rohit + email: rohit@asyncapi.com + url: https://example.com/contact + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0 +``` + +### `Servers` object +The `servers` object in an AsyncAPI document is a map of `server` objects that defines the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. The `server` object is used to capture details such as URIs, protocols and security configuration. + +The purpose of the `servers` object is to provide the necessary information for clients to connect to the message broker or server and participate in the message exchange or listen to the events. By defining multiple servers, the AsyncAPI document can accommodate different environments or deployment scenarios, such as production, staging, or development. + +The `servers` object typically includes the following properties(few are mandatory, few are optional) for each server: + +- url: The URL or address of the server. +- protocol: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). +- description: A brief description or label for the server. +- variables: Variables that can be used to parameterize the server URL, allowing dynamic configuration based on runtime factors. + +```mermaid +graph LR +A[servers] +B[production] +C[url] +D[protocol] +E[description] +F[staging] +G[url] +H[protocol] +I[description] + +A -->|1| B +B -->|2| C +B -->|3| D +B -->|4| E +A -->|5| F +F -->|6| G +F -->|7| H +F -->|8| I +``` + +Here's a code example of the servers object with multiple servers in an AsyncAPI document: +```json +{ + "servers": { + "development": { + "url": "development.my-server.com", + "description": "Development server", + "protocol": "amqp", + "protocolVersion": "0.9.1" + }, + "staging": { + "url": "staging.exmaple-server.com", + "description": "Staging server", + "protocol": "amqp", + "protocolVersion": "0.9.1" + }, + "production": { + "url": "api.demo-server.com", + "description": "Production server", + "protocol": "amqp", + "protocolVersion": "0.9.1" + } + } +} +``` + +### `Channels` object +The `channels` object in an AsyncAPI document hold the relative paths to the individual channels and their operations. Channel paths are relative to servers. +The `channels` represents the communication pathways through which messages are exchanged. It defines the events or topics that applications can subscribe to or publish messages on. Each channel can have properties such as a description, message definitions, and parameters. + +The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. + +The `channels` object typically includes properties for each channel, such as: + +- description: A brief description of the channel, providing additional context and details of the message. +- parameters: Optional parameters associated with the channel, allowing customization or configuration options. +- publish: Defines the message format and structure for publishing messages on the channel basically for the publish operation. +- subscribe: Defines the message format and structure for subscribing to messages on the channel. + +Some of the properties are optional +```mermaid +graph LR +A[channels] +B[channel1] +C[description] +D[publish] +E[subscribe] +F[message] +G[parameters] +H[channel2] +I[description] +J[publish] +K[subscribe] +L[message] +M[parameters] + +A -->|1| B +B -->|2| C +B -->|3| D +B -->|4| E +D -->|5| F +E -->|6| F +F -->|7| G +A -->|8| H +H -->|9| I +H -->|10| J +H -->|11| K +J -->|12| L +K -->|13| L +L -->|14| M +``` + +Here's a code example illustrating the structure of the channels object in an AsyncAPI document: + +Visual representation of the above code example: +```mermaid +graph LR +A[channels] +B[userCreated] +C[description] +D[publish] +E[message] +F[$ref] +G[userCreatedMessage] +H[userDeleted] +I[description] +J[subscribe] +K[message] +L[$ref] +M[userDeletedMessage] + +A -->|1| B +B -->|2| C +B -->|3| D +D -->|4| E +E -->|5| F +F -->|6| G +A -->|7| H +H -->|8| I +H -->|9| J +J -->|10| K +K -->|11| L +L -->|12| M +``` + +### `Components` object +The `components` object in an AsyncAPI document serves as a container for reusable structures or definitions that can be used across different parts of the AsyncAPI document. It allows you to define and manage common elements such as message schemas, security schemes, headers, and other custom components that are referenced throughout the API specification. + +All objects defined within the `components` object will have no effect on the spcific API unless they are explicitly referenced from properties outside the components object. + +The purpose of the `components` object is to promote reusability and maintainability of the AsyncAPI document. By centralizing common definitions in the components section, you can avoid duplicating code and ensure consistency across different parts of the API specification. It also enhances the readability and understandability of the document by providing a clear separation of concerns. + +The `components` object includes 'sub-objects' such as: + +- schemas: Defines message schemas or payload structures used within the API. +- securitySchemes: Specifies the security schemes or authentication mechanisms used by the API. +- parameters: Contains reusable parameters that can be used in various parts of the AsyncAPI document. +- messageTraits: Represents common traits or characteristics that can be applied to messages. +- operationTraits: Represents common traits or characteristics that can be applied to operations. +- correlationIds: Defines reusable correlation identifier objects that can be used to correlate messages. +- message: Represents a single message object that can be referenced throughout the AsyncAPI document. + +Here's a code example of the components object in an AsyncAPI document: +```json +{ + "components": { + "schemas": { + "Category": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + } + }, + "Example": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } + }, + "messages": { + "userSignUp": { + "summary": "Action to sign a user up.", + "description": "Multiline description of what this action does.\nHere you have another line.\n", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + } + ], + "headers": { + "type": "object", + "properties": { + "applicationInstanceId": { + "description": "Unique identifier for a given instance of the publishing application", + "type": "string" + } + } + }, + "payload": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/userCreate" + }, + "signup": { + "$ref": "#/components/schemas/signup" + } + } + } + } + }, + "parameters": { + "userId": { + "description": "Id of the user.", + "schema": { + "type": "string" + } + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } +} +``` +```mermaid +graph LR +A[components] +B[schemas] +C[Category] +D[Tag] +E[Example] +F[messages] +G[userSignUp] +H[headers] +I[payload] +J[parameters] +K[correlationIds] +L[messageTraits] +M[userId] +N[commonHeaders] + +A -->|1| B +B -->|2| C +B -->|3| D +B -->|4| E +A -->|5| F +F -->|6| G +G -->|7| H +G -->|8| I +A -->|9| J +J -->|10| M +A -->|11| K +K -->|12| L +A -->|13| L +L -->|14| N +H -->|15| N +I -->|16| C +I -->|17| D +E -->|18| F +``` \ No newline at end of file From 4831508bbc79797ed651ac80e3bf707b2b1d33b1 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Tue, 11 Jul 2023 10:35:56 +0530 Subject: [PATCH 02/22] Revised draft for Structure doc --- .../concepts/asyncapi-document/structure.md | 639 ++++++++++-------- 1 file changed, 339 insertions(+), 300 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index cd77da1770a..d727a62b55d 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -2,17 +2,10 @@ title: AsyncAPI Structure weight: 32 --- - - -## What's a AysncAPI Document? -An AsyncAPI document is a file written in the AsyncAPI specification format. It is a machine-readable document that describes the structure, format, and behavior of a specific asynchronous API or event-driven API. The document provides a standardized way to define the messages, topics, channels, protocols, and other components involved in the communication. - -An AsyncAPI document typically has a YAML or JSON format and contains various sections that define different aspects of the API like a structure that defines and explains what the specific API needs to do or does. +The structure of a AsyncAPI document can be defined as a specific format in which the document of the specification is to be written. An AsyncAPI document may be made up of a single document or be divided into multiple, connected parts at the discretion of the developer. In the latter case, Reference Objects are used. The structure of a AsyncAPI document has certain fields that need to be followed and implemented. ## Root Elements -Root elements provide a overview of the API's characteristics and behavior.These root elements collectively define the structure, metadata, endpoints, 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 collectively define the structure, metadata, endpoints, channels, components and more of a AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. ```mermaid graph LR @@ -20,24 +13,20 @@ A[asyncapi] B[info] C[servers] D[channels] -E[components] -F[security] -G[tags] -H[externalDocs] - -A -->|1| B -A -->|2| C -A -->|3| D -A -->|4| E -A -->|5| F -A -->|6| G -A -->|7| H +E[operations] +F[components] + +A --> B +A --> C +A --> D +A --> E +A --> F ``` ### `Info` object The `info` object in an AsyncAPI document provides essential information about the API in the form of fields such as title, version, description, contact details and license. It serves as metadata that gives consumers a high-level understanding of the API's purpose and functionality. -The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, Info is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. +The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. The `info` object includes properties such as: @@ -47,49 +36,53 @@ The `info` object includes properties such as: - termsOfService: The URL or document specifying the terms of service for using the API. - contact: Contact information for the owner or maintainer of the API, including name, email, and URL. - license: Information about the license under which the API is provided, including name and URL. +- tags: A list of tags for application API documentation control. Tags can be used for logical grouping of applications. +- externalDocs: Additional external documentation of the exposed API. ```mermaid graph LR -A[info] -B[title] -C[version] -D[description] -E[termsOfService] -F[contact] -G[name] -H[email] -I[url] -J[license] -K[name] -L[url] - -A -->|1| B -A -->|2| C -A -->|3| D -A -->|4| E -A -->|5| F -F -->|6| G -F -->|7| H -F -->|8| I -A -->|9| J -J -->|10| K -J -->|11| L + 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 ``` Below is a example of the `info` object in the AsyncAPI document: ```yaml +asyncapi: 3.0.0 info: - title: My AsyncAPI Example + title: My Event-Driven API version: 1.0.0 - description: An example of info object - termsOfService: https://example.com/terms + description: This API provides real-time event streaming capabilities. + termsOfService: https://example.com/terms-of-service contact: name: Rohit email: rohit@asyncapi.com - url: https://example.com/contact license: name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + tags: + - name: Events + description: APIs related to event streaming + - name: Authentication + description: APIs for authentication and authorization + externalDocs: + description: Additional documentation + url: https://example.com/docs ``` ### `Servers` object @@ -99,136 +92,191 @@ The purpose of the `servers` object is to provide the necessary information for The `servers` object typically includes the following properties(few are mandatory, few are optional) for each server: -- url: The URL or address of the server. +- host: The server host name. It may include the port. This field supports Server Variables. - protocol: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). -- description: A brief description or label for the server. -- variables: Variables that can be used to parameterize the server URL, allowing dynamic configuration based on runtime factors. +- protocolVersion: The version of the protocol used for connection. +- pathname: The path to a resource in the host. +- description: An optional string describing the server. +- title: A human-friendly title for the server. +- summary: A short 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. +- 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. ```mermaid graph LR -A[servers] -B[production] -C[url] -D[protocol] -E[description] -F[staging] -G[url] -H[protocol] -I[description] - -A -->|1| B -B -->|2| C -B -->|3| D -B -->|4| E -A -->|5| F -F -->|6| G -F -->|7| H -F -->|8| I + A[server] + B(host) + C(pathname) + D(protocol) + E(description) + + A --> B + A --> C + A --> D + A --> E ``` Here's a code example of the servers object with multiple servers in an AsyncAPI document: -```json -{ - "servers": { - "development": { - "url": "development.my-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "staging": { - "url": "staging.exmaple-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "production": { - "url": "api.demo-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - } -} +```yaml +host: rabbitmq.in.mycompany.com:5672 +pathname: /production +protocol: amqp +description: Production RabbitMQ broker (uses the `production` vhost). ``` ### `Channels` object -The `channels` object in an AsyncAPI document hold the relative paths to the individual channels and their operations. Channel paths are relative to servers. -The `channels` represents the communication pathways through which messages are exchanged. It defines the events or topics that applications can subscribe to or publish messages on. Each channel can have properties such as a description, message definitions, and parameters. +The `channels` object in an AsyncAPI document hold the relative paths to the individual channels and their operations. Channel paths are relative to servers. The `channels` represents the communication pathways through which messages are exchanged. The `channel` object sescribes a shared communication channel. The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. The `channels` object typically includes properties for each channel, such as: -- description: A brief description of the channel, providing additional context and details of the message. -- parameters: Optional parameters associated with the channel, allowing customization or configuration options. -- publish: Defines the message format and structure for publishing messages on the channel basically for the publish operation. -- subscribe: Defines the message format and structure for subscribing to messages on the channel. +- address: An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". +- messages: A map of the messages that will be sent to this channel by any application at any time. +- title: A human-friendly title for the channel. +- summary: A short summary of the channel. +- description: A optional 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 is absent or empty, this channel must be available on all the servers defined in the `Servers` Object. +- parameters: A map of the parameters included in the channel address. +- tags: A list of tags for logical grouping of 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. -Some of the properties are optional ```mermaid graph LR -A[channels] -B[channel1] -C[description] -D[publish] -E[subscribe] -F[message] -G[parameters] -H[channel2] -I[description] -J[publish] -K[subscribe] -L[message] -M[parameters] - -A -->|1| B -B -->|2| C -B -->|3| D -B -->|4| E -D -->|5| F -E -->|6| F -F -->|7| G -A -->|8| H -H -->|9| I -H -->|10| J -H -->|11| K -J -->|12| L -K -->|13| L -L -->|14| M + A[channels] + 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 ``` Here's a code example illustrating the structure of the channels object in an AsyncAPI document: +```yaml +address: 'users.{userId}' +title: Users channel +description: This channel is used to exchange messages about user events. +messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +parameters: + userId: + $ref: '#/components/parameters/userId' +servers: + - $ref: '#/servers/rabbitmqInProd' + - $ref: '#/servers/rabbitmqInStaging' +bindings: + amqp: + is: queue + queue: + exclusive: true +tags: + - name: user + description: User-related messages +externalDocs: + description: 'Find more info here' + url: 'https://example.com' +``` +### `Operations` object +The `operations` object holds a dictionary with all the operations the application must implement. Each `operation` object define the specific operation that needs to be implemented. The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. + +The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. It serves as a reference for developers, tools, and libraries to understand the required operations and their associated properties, allowing for better implementation, documentation, and code generation. + +The `operations` object typically include properties for each `operation` object, such as: +- 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 receiving messages from the given channel. +- channel: A `$ref` pointer to the definition of the channel in which this operation is performed. +- 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. +- 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 request-reply operation. -Visual representation of the above code example: ```mermaid graph LR -A[channels] -B[userCreated] -C[description] -D[publish] -E[message] -F[$ref] -G[userCreatedMessage] -H[userDeleted] -I[description] -J[subscribe] -K[message] -L[$ref] -M[userDeletedMessage] - -A -->|1| B -B -->|2| C -B -->|3| D -D -->|4| E -E -->|5| F -F -->|6| G -A -->|7| H -H -->|8| I -H -->|9| J -J -->|10| K -K -->|11| L -L -->|12| M + A[operations] + 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 +``` + +Here's a code example illustrating the structure of the `operations` object in an AsyncAPI document: +```yaml +title: User sign up +summary: Action to sign a user up. +description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send +security: + - petstore_auth: + - write:pets + - read:pets +tags: + - name: user + - name: signup + - name: register +bindings: + amqp: + ack: false +traits: + - $ref: "#/components/operationTraits/kafka" +messages: + - $ref: '#/components/messages/userSignedUp' +reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/components/messages/userSignedUpReply' ``` ### `Components` object @@ -238,150 +286,141 @@ All objects defined within the `components` object will have no effect on the sp The purpose of the `components` object is to promote reusability and maintainability of the AsyncAPI document. By centralizing common definitions in the components section, you can avoid duplicating code and ensure consistency across different parts of the API specification. It also enhances the readability and understandability of the document by providing a clear separation of concerns. -The `components` object includes 'sub-objects' such as: - -- schemas: Defines message schemas or payload structures used within the API. -- securitySchemes: Specifies the security schemes or authentication mechanisms used by the API. -- parameters: Contains reusable parameters that can be used in various parts of the AsyncAPI document. +The `components` object includes properties such as: + +- schemas: An object to hold reusable Schema Object. +- servers: An object to hold reusable Server Objects. +- channels: An object to hold reusable Channel Objects. +- operations: An object to hold reusable Operation Item Objects. +- messages: An object to hold reusable Message Objects. +- securitySchemes: An object to hold reusable Security Scheme Objects. +- serverVariables: An object to hold reusable Server Variable Objects. +- parameters: Contains reusable parameter objects that can be used in various parts of the AsyncAPI document. +- correlationIds: An object to hold reusable Correlation ID Objects. +- replies: An object to hold reusable Operation Reply Objects. +- replyAddresses: An object to hold reusable Operation Reply Address Objects. +- externalDocs: An object to hold reusable External Documentation Objects. +- tags: An object to hold reusable Tag Objects. +- operationTraits: An object to hold reusable Operation Trait Objects. - messageTraits: Represents common traits or characteristics that can be applied to messages. -- operationTraits: Represents common traits or characteristics that can be applied to operations. -- correlationIds: Defines reusable correlation identifier objects that can be used to correlate messages. -- message: Represents a single message object that can be referenced throughout the AsyncAPI document. +- serverBindings: An object to hold reusable Server Bindings Objects. +- channelBindings: An object to hold reusable Channel Bindings Objects. +- operationBindings: An object to hold reusable Operation Bindings Objects. +- messageBindings: An object to hold reusable Message Bindings Objects. -Here's a code example of the components object in an AsyncAPI document: -```json -{ - "components": { - "schemas": { - "Category": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - } - }, - "Tag": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - } - }, - "Example": { - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "schema": { - "$ref": "path/to/user-create.avsc#/UserCreate" - } - } - }, - "messages": { - "userSignUp": { - "summary": "Action to sign a user up.", - "description": "Multiline description of what this action does.\nHere you have another line.\n", - "tags": [ - { - "name": "user" - }, - { - "name": "signup" - } - ], - "headers": { - "type": "object", - "properties": { - "applicationInstanceId": { - "description": "Unique identifier for a given instance of the publishing application", - "type": "string" - } - } - }, - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/userCreate" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "correlationIds": { - "default": { - "description": "Default Correlation ID", - "location": "$message.header#/correlationId" - } - }, - "messageTraits": { - "commonHeaders": { - "headers": { - "type": "object", - "properties": { - "my-app-header": { - "type": "integer", - "minimum": 0, - "maximum": 100 - } - } - } - } - } - } -} -``` ```mermaid graph LR -A[components] -B[schemas] -C[Category] -D[Tag] -E[Example] -F[messages] -G[userSignUp] -H[headers] -I[payload] -J[parameters] -K[correlationIds] -L[messageTraits] -M[userId] -N[commonHeaders] - -A -->|1| B -B -->|2| C -B -->|3| D -B -->|4| E -A -->|5| F -F -->|6| G -G -->|7| H -G -->|8| I -A -->|9| J -J -->|10| M -A -->|11| K -K -->|12| L -A -->|13| L -L -->|14| N -H -->|15| N -I -->|16| C -I -->|17| D -E -->|18| F -``` \ No newline at end of file + A[components] + B(schemas) + C(Category) + D(Tag) + G(servers) + H(development) + I(serverVariables) + L(channels) + P(messages) + U(parameters) + W(correlationIds) + Y(messageTraits) + + A --> B + B --> C + B --> D + A --> G + G --> H + H --> I + A --> L + A --> P + A --> U + A --> W + A --> Y +``` + +Here's a code example of the components object in an AsyncAPI document: +```yaml +components: + schemas: + Category: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + Tag: + type: object + properties: + id: + type: integer + format: int64 + name: + type: string + AvroExample: + schemaFormat: application/vnd.apache.avro+json;version=1.9.0 + schema: + $ref: 'path/to/user-create.avsc/#UserCreate' + servers: + development: + url: "{stage}.in.mycompany.com:{port}" + description: RabbitMQ broker + protocol: amqp + protocolVersion: 0-9-1 + variables: + stage: + $ref: "#/components/serverVariables/stage" + port: + $ref: "#/components/serverVariables/port" + serverVariables: + stage: + default: demo + description: This value is assigned by the service provider, in this example `mycompany.com` + port: + enum: [5671, 5672] + default: 5672 + channels: + user/signedup: + subscribe: + message: + $ref: "#/components/messages/userSignUp" + messages: + userSignUp: + summary: Action to sign a user up. + description: | + Multiline description of what this action does. + Here you have another line. + tags: + - name: user + - name: signup + headers: + type: object + properties: + applicationInstanceId: + description: Unique identifier for a given instance of the publishing application + type: string + payload: + type: object + properties: + user: + $ref: "#/components/schemas/userCreate" + signup: + $ref: "#/components/schemas/signup" + parameters: + userId: + description: Id of the user. + schema: + type: string + correlationIds: + default: + description: Default Correlation ID + location: $message.header#/correlationId + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 +``` From e9368dfa468dc59606c77f72ef72b91c175e118c Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Tue, 11 Jul 2023 22:18:37 +0530 Subject: [PATCH 03/22] fix: minor edits, changes based on suggestions --- .../concepts/asyncapi-document/structure.md | 138 +++++++++--------- 1 file changed, 72 insertions(+), 66 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index d727a62b55d..fc22c6fde6c 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -2,10 +2,11 @@ title: AsyncAPI Structure weight: 32 --- -The structure of a AsyncAPI document can be defined as a specific format in which the document of the specification is to be written. An AsyncAPI document may be made up of a single document or be divided into multiple, connected parts at the discretion of the developer. In the latter case, Reference Objects are used. The structure of a AsyncAPI document has certain fields that need to be followed and implemented. +The structure of a AsyncAPI document can be defined as a specific format in which the document of the specification is to be written. An AsyncAPI document may be made up of a single document or be divided into multiple, connected parts at your discretion. In the latter case, Reference Objects are used. The structure of a AsyncAPI document has certain fields that need to be followed and implemented. +Structure of a AsyncAPI document lays out the blueprint for you to write down your specification based on your application. ## Root Elements -Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior.These root elements collectively define the structure, metadata, endpoints, channels, components and more of a 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 collectively define the structure, metadata, endpoints, channels, components and more of a AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. ```mermaid graph LR @@ -30,15 +31,16 @@ The purpose of the `info` object is to provide descriptive and contact informati The `info` object includes properties such as: -- title: The title of the API. -- version: The version of the API. -- description: A brief description explaining the purpose and features of the API. -- termsOfService: The URL or document specifying the terms of service for using the API. -- contact: Contact information for the owner or maintainer of the API, including name, email, and URL. -- license: Information about the license under which the API is provided, including name and URL. -- tags: A list of tags for application API documentation control. Tags can be used for logical grouping of applications. -- externalDocs: Additional external documentation of the exposed API. +- `title`: The title of the API. +- `version`: The version of the API. +- `description`: A brief description explaining the purpose and features of the API. +- `termsOfService`: The URL or document specifying the terms of service for using the API. +- `contact`: Contact information for the owner or maintainer of the API, including name, email, and URL. +- `license`: Information about the license under which the API is provided, including name and URL. +- `tags`: A list of tags for application API documentation control. Tags can be used for logical grouping of applications. +- `externalDocs`: Additional external documentation of the exposed API. +Here's a visual representation of the `info` object and its properties: ```mermaid graph LR B(info) @@ -92,18 +94,19 @@ The purpose of the `servers` object is to provide the necessary information for The `servers` object typically includes the following properties(few are mandatory, few are optional) for each server: -- host: The server host name. It may include the port. This field supports Server Variables. -- protocol: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). -- protocolVersion: The version of the protocol used for connection. -- pathname: The path to a resource in the host. -- description: An optional string describing the server. -- title: A human-friendly title for the server. -- summary: A short 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. -- 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. - +- `host`: The server host name. It may include the port. This field supports Server Variables. +- `protocol`: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). +- `protocolVersion`: The version of the protocol used for connection. +- `pathname`: The path to a resource in the host. +- `description`: An optional string describing the server. +- `title`: A human-friendly title for the server. +- `summary`: A short 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. +- `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] @@ -133,17 +136,18 @@ The purpose of the `channels` object is to provide a structured way to define th The `channels` object typically includes properties for each channel, such as: -- address: An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". -- messages: A map of the messages that will be sent to this channel by any application at any time. -- title: A human-friendly title for the channel. -- summary: A short summary of the channel. -- description: A optional 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 is absent or empty, this channel must be available on all the servers defined in the `Servers` Object. -- parameters: A map of the parameters included in the channel address. -- tags: A list of tags for logical grouping of 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. - +- `address`: An *optional* 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. +- `title`: A human-readable title for the channel. +- `summary`: A short yet brief summary of the channel. +- `description`: A *optional* 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 is absent or empty, this channel must be available on all the servers defined in the `Servers` Object. +- `parameters`: A map of the parameters included in the channel address. +- `tags`: A list of tags for logical grouping of 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` object and its properties: ```mermaid graph LR A[channels] @@ -202,19 +206,20 @@ The `operations` object holds a dictionary with all the operations the applicati The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. It serves as a reference for developers, tools, and libraries to understand the required operations and their associated properties, allowing for better implementation, documentation, and code generation. The `operations` object typically include properties for each `operation` object, such as: -- 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 receiving messages from the given channel. -- channel: A `$ref` pointer to the definition of the channel in which this operation is performed. -- 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. -- 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 request-reply operation. - +- `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 receiving messages from the given channel. +- `channel`: A `$ref` pointer to the definition of the channel in which this operation is performed. +- `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. +- `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 request-reply operation. + +Here's a visual representation of the `operations` object and its properties: ```mermaid graph LR A[operations] @@ -288,26 +293,27 @@ The purpose of the `components` object is to promote reusability and maintainabi The `components` object includes properties such as: -- schemas: An object to hold reusable Schema Object. -- servers: An object to hold reusable Server Objects. -- channels: An object to hold reusable Channel Objects. -- operations: An object to hold reusable Operation Item Objects. -- messages: An object to hold reusable Message Objects. -- securitySchemes: An object to hold reusable Security Scheme Objects. -- serverVariables: An object to hold reusable Server Variable Objects. -- parameters: Contains reusable parameter objects that can be used in various parts of the AsyncAPI document. -- correlationIds: An object to hold reusable Correlation ID Objects. -- replies: An object to hold reusable Operation Reply Objects. -- replyAddresses: An object to hold reusable Operation Reply Address Objects. -- externalDocs: An object to hold reusable External Documentation Objects. -- tags: An object to hold reusable Tag Objects. -- operationTraits: An object to hold reusable Operation Trait Objects. -- messageTraits: Represents common traits or characteristics that can be applied to messages. -- serverBindings: An object to hold reusable Server Bindings Objects. -- channelBindings: An object to hold reusable Channel Bindings Objects. -- operationBindings: An object to hold reusable Operation Bindings Objects. -- messageBindings: An object to hold reusable Message Bindings Objects. - +- `schemas`: An object to hold reusable Schema Object. +- `servers`: An object to hold reusable Server Objects. +- `channels`: An object to hold reusable Channel Objects. +- `operations`: An object to hold reusable Operation Item Objects. +- `messages`: An object to hold reusable Message Objects. +- `securitySchemes`: An object to hold reusable Security Scheme Objects. +- `serverVariables`: An object to hold reusable Server Variable Objects. +- `parameters`: Contains reusable parameter objects that can be used in various parts of the AsyncAPI document. +- `correlationIds`: An object to hold reusable Correlation ID Objects. +- `replies`: An object to hold reusable Operation Reply Objects. +- `replyAddresses`: An object to hold reusable Operation Reply Address Objects. +- `externalDocs`: An object to hold reusable External Documentation Objects. +- `tags`: An object to hold reusable Tag Objects. +- `operationTraits`: An object to hold reusable Operation Trait Objects. +- `messageTraits`: Represents common traits or characteristics that can be applied to messages. +- `serverBindings`: An object to hold reusable Server Bindings Objects. +- `channelBindings`: An object to hold reusable Channel Bindings Objects. +- `operationBindings`: An object to hold reusable Operation Bindings Objects. +- `messageBindings`: An object to hold reusable Message Bindings Objects. + +Here's a visual representation of the `components` object and its properties: ```mermaid graph LR A[components] From 698906a845ff1ad22015e07b1ba3148306a173e4 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 12:03:50 +0530 Subject: [PATCH 04/22] Update pages/docs/concepts/asyncapi-document/structure.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- pages/docs/concepts/asyncapi-document/structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index fc22c6fde6c..aad7665c28f 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -6,7 +6,7 @@ The structure of a AsyncAPI document can be defined as a specific format in whic Structure of a AsyncAPI document lays out the blueprint for you to write down your specification based on your application. ## Root Elements -Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements collectively define the structure, metadata, endpoints, channels, components and more of a 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 collectively define the structure, metadata, channels, components and more of a AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. ```mermaid graph LR From 20b67031dc94121e36960a13205f642b23d24456 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 12:04:45 +0530 Subject: [PATCH 05/22] fix: remove redundant sentence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- pages/docs/concepts/asyncapi-document/structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index aad7665c28f..98d1acf484e 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -88,7 +88,7 @@ info: ``` ### `Servers` object -The `servers` object in an AsyncAPI document is a map of `server` objects that defines the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. The `server` object is used to capture details such as URIs, protocols and security configuration. +The `servers` object in an AsyncAPI document is a map of `server` objects that defines the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. The purpose of the `servers` object is to provide the necessary information for clients to connect to the message broker or server and participate in the message exchange or listen to the events. By defining multiple servers, the AsyncAPI document can accommodate different environments or deployment scenarios, such as production, staging, or development. From eabf9c0725bc5a452b85f53dca1909f397aa4dd8 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 12:28:02 +0530 Subject: [PATCH 06/22] fix: mistaken use of `operations` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- pages/docs/concepts/asyncapi-document/structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 98d1acf484e..115ad738bc0 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -130,7 +130,7 @@ description: Production RabbitMQ broker (uses the `production` vhost). ``` ### `Channels` object -The `channels` object in an AsyncAPI document hold the relative paths to the individual channels and their operations. Channel paths are relative to servers. The `channels` represents the communication pathways through which messages are exchanged. The `channel` object sescribes a shared communication channel. +The `channels` object in an AsyncAPI document hold the relative paths to the individual channels. Channel paths are relative to servers. The `channels` represents the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. From 195bc928b64c064309166a54358fec2eafaf7300 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 12:32:26 +0530 Subject: [PATCH 07/22] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- pages/docs/concepts/asyncapi-document/structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 115ad738bc0..39889214a95 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -92,7 +92,7 @@ The `servers` object in an AsyncAPI document is a map of `server` objects that d The purpose of the `servers` object is to provide the necessary information for clients to connect to the message broker or server and participate in the message exchange or listen to the events. By defining multiple servers, the AsyncAPI document can accommodate different environments or deployment scenarios, such as production, staging, or development. -The `servers` object typically includes the following properties(few are mandatory, few are optional) for each server: +The `servers` object typically includes the following properties for each server: - `host`: The server host name. It may include the port. This field supports Server Variables. - `protocol`: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). From 8e63c02e21201c8340aa7665dcc17125fb185724 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 12:34:31 +0530 Subject: [PATCH 08/22] Update structure.md --- pages/docs/concepts/asyncapi-document/structure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 39889214a95..abd2df564da 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -136,11 +136,11 @@ The purpose of the `channels` object is to provide a structured way to define th The `channels` object typically includes properties for each channel, such as: -- `address`: An *optional* string representation of this channel's address. +- `address`: An 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. - `title`: A human-readable title for the channel. - `summary`: A short yet brief summary of the channel. -- `description`: A *optional* description of the channel, providing additional context and details of the message. +- `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 is absent or empty, this channel must be available on all the servers defined in the `Servers` Object. - `parameters`: A map of the parameters included in the channel address. - `tags`: A list of tags for logical grouping of channels. From 76706d6cfd8f207bbdcfd7d342a33074df98cdb0 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 17:02:38 +0530 Subject: [PATCH 09/22] Apply suggestions from code review Co-authored-by: Sergio Moya <1083296+smoya@users.noreply.github.com> --- pages/docs/concepts/asyncapi-document/structure.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index abd2df564da..049b79315ba 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -1,9 +1,9 @@ --- -title: AsyncAPI Structure +title: AsyncAPI document structure weight: 32 --- The structure of a AsyncAPI document can be defined as a specific format in which the document of the specification is to be written. An AsyncAPI document may be made up of a single document or be divided into multiple, connected parts at your discretion. In the latter case, Reference Objects are used. The structure of a AsyncAPI document has certain fields that need to be followed and implemented. -Structure of a AsyncAPI document lays out the blueprint for you to write down your specification based on your application. +This document lays out the blueprint for you to write down your specification based on your application. ## Root Elements Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements collectively define the structure, metadata, channels, components and more of a AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. @@ -29,7 +29,7 @@ The `info` object in an AsyncAPI document provides essential information about t The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. -The `info` object includes properties such as: +The `info` object includes fields such as: - `title`: The title of the API. - `version`: The version of the API. @@ -150,7 +150,7 @@ The `channels` object typically includes properties for each channel, such as: Here's a visual representation of the `channels` object and its properties: ```mermaid graph LR - A[channels] + A[channel] B(address) C(title) D(description) @@ -201,7 +201,7 @@ externalDocs: url: 'https://example.com' ``` ### `Operations` object -The `operations` object holds a dictionary with all the operations the application must implement. Each `operation` object define the specific operation that needs to be implemented. The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. +The `operations` object holds a dictionary with all the operations the application must implement. The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. It serves as a reference for developers, tools, and libraries to understand the required operations and their associated properties, allowing for better implementation, documentation, and code generation. @@ -222,7 +222,7 @@ The `operations` object typically include properties for each `operation` object Here's a visual representation of the `operations` object and its properties: ```mermaid graph LR - A[operations] + A[operation] B(title) C(summary) D(description) From 03d0f5c98d0a484ef1c0db169d9b426c1142d7d9 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Wed, 12 Jul 2023 17:09:38 +0530 Subject: [PATCH 10/22] Update property introduction sentences --- pages/docs/concepts/asyncapi-document/structure.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 049b79315ba..a8da56c8e4c 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -29,7 +29,7 @@ The `info` object in an AsyncAPI document provides essential information about t The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. -The `info` object includes fields such as: +Some of the fields `info` object holds are: - `title`: The title of the API. - `version`: The version of the API. @@ -92,7 +92,7 @@ The `servers` object in an AsyncAPI document is a map of `server` objects that d The purpose of the `servers` object is to provide the necessary information for clients to connect to the message broker or server and participate in the message exchange or listen to the events. By defining multiple servers, the AsyncAPI document can accommodate different environments or deployment scenarios, such as production, staging, or development. -The `servers` object typically includes the following properties for each server: +Some of the fields `servers` object holds for each server object are: - `host`: The server host name. It may include the port. This field supports Server Variables. - `protocol`: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). @@ -134,7 +134,7 @@ The `channels` object in an AsyncAPI document hold the relative paths to the ind The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. -The `channels` object typically includes properties for each channel, such as: +Some of the fields `channels` object holds for each channel object are: - `address`: An 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. @@ -205,7 +205,8 @@ The `operations` object holds a dictionary with all the operations the applicati The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. It serves as a reference for developers, tools, and libraries to understand the required operations and their associated properties, allowing for better implementation, documentation, and code generation. -The `operations` object typically include properties for each `operation` object, such as: +Some of the fields `operations` object holds for each `operation` object are: + - `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 receiving messages from the given channel. - `channel`: A `$ref` pointer to the definition of the channel in which this operation is performed. - `title`: A human-friendly title for the operation. @@ -291,7 +292,7 @@ All objects defined within the `components` object will have no effect on the sp The purpose of the `components` object is to promote reusability and maintainability of the AsyncAPI document. By centralizing common definitions in the components section, you can avoid duplicating code and ensure consistency across different parts of the API specification. It also enhances the readability and understandability of the document by providing a clear separation of concerns. -The `components` object includes properties such as: +Some of the fields `components` object holds are: - `schemas`: An object to hold reusable Schema Object. - `servers`: An object to hold reusable Server Objects. From 164bb1633793af634ffabb6bbe55f5f25277886b Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Thu, 13 Jul 2023 20:50:57 +0530 Subject: [PATCH 11/22] fix: made the suggested changes --- .../concepts/asyncapi-document/structure.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index a8da56c8e4c..0dfdf1999fc 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -94,7 +94,7 @@ The purpose of the `servers` object is to provide the necessary information for Some of the fields `servers` object holds for each server object are: -- `host`: The server host name. It may include the port. This field supports Server Variables. +- `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 connection. - `pathname`: The path to a resource in the host. @@ -294,25 +294,25 @@ The purpose of the `components` object is to promote reusability and maintainabi Some of the fields `components` object holds are: -- `schemas`: An object to hold reusable Schema Object. -- `servers`: An object to hold reusable Server Objects. -- `channels`: An object to hold reusable Channel Objects. -- `operations`: An object to hold reusable Operation Item Objects. -- `messages`: An object to hold reusable Message Objects. -- `securitySchemes`: An object to hold reusable Security Scheme Objects. -- `serverVariables`: An object to hold reusable Server Variable Objects. -- `parameters`: Contains reusable parameter objects that can be used in various parts of the AsyncAPI document. -- `correlationIds`: An object to hold reusable Correlation ID Objects. -- `replies`: An object to hold reusable Operation Reply Objects. -- `replyAddresses`: An object to hold reusable Operation Reply Address Objects. -- `externalDocs`: An object to hold reusable External Documentation Objects. -- `tags`: An object to hold reusable Tag Objects. -- `operationTraits`: An object to hold reusable Operation Trait Objects. -- `messageTraits`: Represents common traits or characteristics that can be applied to messages. -- `serverBindings`: An object to hold reusable Server Bindings Objects. -- `channelBindings`: An object to hold reusable Channel Bindings Objects. -- `operationBindings`: An object to hold reusable Operation Bindings Objects. -- `messageBindings`: An object to hold reusable Message Bindings Objects. +- `schemas`: An object to hold reusable [Schema Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#schemaObject). +- `servers`: An object to hold reusable [Server Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverObject). +- `channels`: An object to hold reusable [Channel Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelObject). +- `operations`: An object to hold reusable [Operation Item Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). +- `messages`: An object to hold reusable [Messages Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageObject). +- `securitySchemes`: An object to hold reusable [Security Scheme Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#securitySchemeObject). +- `serverVariables`: An object to hold reusable [Server Variable Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverVariableObject). +- `parameters`: Contains reusable [parameter objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#parameterObject) that can be used in various parts of the AsyncAPI document. +- `correlationIds`: An object to hold reusable [Correlation ID Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#correlationIdObject). +- `replies`: An object to hold reusable [Operation Reply Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationReplyObject). +- `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationReplyAddressObject). +- `externalDocs`: An object to hold reusable [External Documentation Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#externalDocumentationObject). +- `tags`: An object to hold reusable [Tag Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#tagObject). +- `operationTraits`: An object to hold reusable [Operation Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationTraitObject). +- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusuable [Message Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageTraitObject). +- `serverBindings`: An object to hold reusable [Server Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverBindingsObject). +- `channelBindings`: An object to hold reusable [Channel Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelBindingsObject). +- `operationBindings`: An object to hold reusable [Operation Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationBindingsObject). +- `messageBindings`: An object to hold reusable [Message Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageBindingsObject). Here's a visual representation of the `components` object and its properties: ```mermaid From 72a5bda5156e9e94a94418ece39411af89b66a50 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Fri, 14 Jul 2023 17:36:03 +0530 Subject: [PATCH 12/22] changes suggested by Sergio --- pages/docs/concepts/asyncapi-document/structure.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 0dfdf1999fc..814f6f3a422 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -6,7 +6,7 @@ The structure of a AsyncAPI document can be defined as a specific format in whic This document lays out the blueprint for you to write down your specification based on your application. ## Root Elements -Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements collectively define the structure, metadata, channels, components and more of a 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 collectively define the metadata, channels, components and more of a AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. ```mermaid graph LR @@ -130,7 +130,7 @@ description: Production RabbitMQ broker (uses the `production` vhost). ``` ### `Channels` object -The `channels` object in an AsyncAPI document hold the relative paths to the individual channels. Channel paths are relative to servers. The `channels` represents the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. +The `channels` object in an AsyncAPI document holds all the individual `channel` objects definitions that the application must use during runtime. The `channels` represents the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. @@ -201,9 +201,9 @@ externalDocs: url: 'https://example.com' ``` ### `Operations` object -The `operations` object holds a dictionary with all the operations the application must implement. The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. +The `operations` object holds a dictionary with all the operations the application must implement. The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. -The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. It serves as a reference for developers, tools, and libraries to understand the required operations and their associated properties, allowing for better implementation, documentation, and code generation. +The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. Some of the fields `operations` object holds for each `operation` object are: @@ -386,10 +386,6 @@ components: enum: [5671, 5672] default: 5672 channels: - user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" messages: userSignUp: summary: Action to sign a user up. From 399e762c00e139fb80986c24ca850fefdc49c783 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Tue, 17 Oct 2023 23:57:41 +0530 Subject: [PATCH 13/22] Update the introduction along with grammatical fix --- .../concepts/asyncapi-document/structure.md | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 814f6f3a422..0d168b61854 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -2,11 +2,10 @@ title: AsyncAPI document structure weight: 32 --- -The structure of a AsyncAPI document can be defined as a specific format in which the document of the specification is to be written. An AsyncAPI document may be made up of a single document or be divided into multiple, connected parts at your discretion. In the latter case, Reference Objects are used. The structure of a AsyncAPI document has certain fields that need to be followed and implemented. -This document lays out the blueprint for you to write down your specification based on your application. +The structure of an AsyncAPI document can be defined as a specific format in which the document of the specification is to be written and defined. The structure of an AsyncAPI document has certain fields that need to be followed and implemented. ## 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 a 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 behaviour. 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 behaviour. ```mermaid graph LR @@ -63,7 +62,7 @@ graph LR B --> P ``` -Below is a example of the `info` object in the AsyncAPI document: +Below is an example of the `info` object in the AsyncAPI document: ```yaml asyncapi: 3.0.0 info: @@ -96,11 +95,11 @@ Some of the fields `servers` object holds for each server object are: - `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 connection. +- `protocolVersion`: The version of the protocol used for the connection. - `pathname`: The path to a resource in the host. - `description`: An optional string describing the server. - `title`: A human-friendly title for the server. -- `summary`: A short summary of 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. - `externalDocs`: Additional external documentation for this server. @@ -130,18 +129,18 @@ description: Production RabbitMQ broker (uses the `production` vhost). ``` ### `Channels` object -The `channels` object in an AsyncAPI document holds all the individual `channel` objects definitions that the application must use during runtime. The `channels` represents the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. +The `channels` object in an AsyncAPI document holds all the individual `channel` object definitions that the application must use during runtime. The `channels` represent the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. Some of the fields `channels` object holds for each channel object are: -- `address`: An string representation of this channel's address. +- `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. - `title`: A human-readable title for the channel. - `summary`: A short yet brief 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 is absent or empty, this channel must be available on all the servers defined in the `Servers` Object. +- `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` Object. - `parameters`: A map of the parameters included in the channel address. - `tags`: A list of tags for logical grouping of channels. - `externalDocs`: Additional external documentation for this channel. @@ -207,7 +206,7 @@ The `operations` object is located within the AsyncAPI document and is separate Some of the fields `operations` object holds for each `operation` object are: -- `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 receiving messages from the given channel. +- `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. - `title`: A human-friendly title for the operation. - `summary`: A short summary of what the operation is about. @@ -288,7 +287,7 @@ reply: ### `Components` object The `components` object in an AsyncAPI document serves as a container for reusable structures or definitions that can be used across different parts of the AsyncAPI document. It allows you to define and manage common elements such as message schemas, security schemes, headers, and other custom components that are referenced throughout the API specification. -All objects defined within the `components` object will have no effect on the spcific API unless they are explicitly referenced from properties outside the components object. +All objects defined within the `components` object will not affect the specific API unless they are explicitly referenced from properties outside the components object. The purpose of the `components` object is to promote reusability and maintainability of the AsyncAPI document. By centralizing common definitions in the components section, you can avoid duplicating code and ensure consistency across different parts of the API specification. It also enhances the readability and understandability of the document by providing a clear separation of concerns. @@ -308,7 +307,7 @@ Some of the fields `components` object holds are: - `externalDocs`: An object to hold reusable [External Documentation Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#externalDocumentationObject). - `tags`: An object to hold reusable [Tag Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#tagObject). - `operationTraits`: An object to hold reusable [Operation Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationTraitObject). -- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusuable [Message Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageTraitObject). +- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageTraitObject). - `serverBindings`: An object to hold reusable [Server Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverBindingsObject). - `channelBindings`: An object to hold reusable [Channel Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelBindingsObject). - `operationBindings`: An object to hold reusable [Operation Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationBindingsObject). From b391119820dabc0a94c8e0177ac7131d8fe23a3b Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 18 Oct 2023 00:18:52 +0530 Subject: [PATCH 14/22] fix: edits suggested by Alejandra --- .../concepts/asyncapi-document/structure.md | 87 +++++++++++++++---- 1 file changed, 69 insertions(+), 18 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 0d168b61854..169fa9ef47c 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -1,7 +1,8 @@ --- title: AsyncAPI document structure -weight: 32 +weight: 60 --- + The structure of an AsyncAPI document can be defined as a specific format in which the document of the specification is to be written and defined. The structure of an AsyncAPI document has certain fields that need to be followed and implemented. ## Root Elements @@ -23,7 +24,7 @@ A --> E A --> F ``` -### `Info` object +### `Info` Object The `info` object in an AsyncAPI document provides essential information about the API in the form of fields such as title, version, description, contact details and license. It serves as metadata that gives consumers a high-level understanding of the API's purpose and functionality. The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. @@ -86,7 +87,7 @@ info: url: https://example.com/docs ``` -### `Servers` object +### `Servers` Object The `servers` object in an AsyncAPI document is a map of `server` objects that defines the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. The purpose of the `servers` object is to provide the necessary information for clients to connect to the message broker or server and participate in the message exchange or listen to the events. By defining multiple servers, the AsyncAPI document can accommodate different environments or deployment scenarios, such as production, staging, or development. @@ -112,23 +113,72 @@ graph LR B(host) C(pathname) D(protocol) - E(description) + E(protocolVersion) + F(description) + G(title) + H(summary) + I(security) + J(tags) + K(externalDocs) + L(bindings) A --> B A --> C A --> D A --> E + A --> F + A --> G + A --> H + A --> I + A --> J + A --> K + A --> L ``` Here's a code example of the servers object with multiple servers in an AsyncAPI document: ```yaml -host: rabbitmq.in.mycompany.com:5672 -pathname: /production -protocol: amqp -description: Production RabbitMQ broker (uses the `production` vhost). +servers: + - host: rabbitmq.in.mycompany.com:5672 + pathname: /production + protocol: amqp + protocolVersion: 1.0 + description: Production RabbitMQ broker (uses the `production` vhost). + title: Production Server + summary: Production environment server + security: + - apiKey: [] + tags: + - name: production + description: Production environment + externalDocs: + description: Additional documentation for the production server + url: https://example.com/docs/production + bindings: + amqp: + exchange: my-exchange + queue: my-queue + - host: rabbitmq.in.mycompany.com:5672 + pathname: /staging + protocol: amqp + protocolVersion: 1.0 + description: Staging RabbitMQ broker (uses the `staging` vhost). + title: Staging Server + summary: Staging environment server + security: + - apiKey: [] + tags: + - name: staging + description: Staging environment + externalDocs: + description: Additional documentation for the staging server + url: https://example.com/docs/staging + bindings: + amqp: + exchange: my-exchange + queue: my-queue ``` -### `Channels` object +### `Channels` Object The `channels` object in an AsyncAPI document holds all the individual `channel` object definitions that the application must use during runtime. The `channels` represent the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. @@ -199,7 +249,8 @@ externalDocs: description: 'Find more info here' url: 'https://example.com' ``` -### `Operations` object + +### `Operations` Object The `operations` object holds a dictionary with all the operations the application must implement. The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. @@ -237,17 +288,17 @@ graph LR M(address) N(channel) - A -->B + A --> B A --> C A --> D - A -->E + A --> E A --> F A --> G A --> H A --> I - A -->J + A --> J A --> K - A -->L + A --> L L --> M L --> N ``` @@ -284,7 +335,7 @@ reply: - $ref: '#/components/messages/userSignedUpReply' ``` -### `Components` object +### `Components` Object The `components` object in an AsyncAPI document serves as a container for reusable structures or definitions that can be used across different parts of the AsyncAPI document. It allows you to define and manage common elements such as message schemas, security schemes, headers, and other custom components that are referenced throughout the API specification. All objects defined within the `components` object will not affect the specific API unless they are explicitly referenced from properties outside the components object. @@ -318,8 +369,8 @@ Here's a visual representation of the `components` object and its properties: graph LR A[components] B(schemas) - C(Category) - D(Tag) + C(category) + D(tag) G(servers) H(development) I(serverVariables) @@ -425,4 +476,4 @@ components: type: integer minimum: 0 maximum: 100 -``` +``` \ No newline at end of file From c83a4fb4697320ef466295cb756aadc7debcb74a Mon Sep 17 00:00:00 2001 From: Rohit Date: Tue, 7 Nov 2023 13:13:17 +0530 Subject: [PATCH 15/22] Update diagram orientation --- pages/docs/concepts/asyncapi-document/structure.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 169fa9ef47c..0df7f23bf1f 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -9,7 +9,7 @@ The structure of an AsyncAPI document can be defined as a specific format in whi Root elements of an AsyncAPI document provide an overview of the API's characteristics and behaviour. 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 behaviour. ```mermaid -graph LR +graph A[asyncapi] B[info] C[servers] @@ -42,7 +42,7 @@ Some of the fields `info` object holds are: Here's a visual representation of the `info` object and its properties: ```mermaid -graph LR +graph B(info) C(title) D(version) @@ -108,7 +108,7 @@ Some of the fields `servers` object holds for each server object are: Here's a visual representation of the `server` object and its properties: ```mermaid -graph LR +graph A[server] B(host) C(pathname) @@ -198,7 +198,7 @@ Some of the fields `channels` object holds for each channel object are: Here's a visual representation of the `channels` object and its properties: ```mermaid -graph LR +graph A[channel] B(address) C(title) @@ -272,7 +272,7 @@ Some of the fields `operations` object holds for each `operation` object are: Here's a visual representation of the `operations` object and its properties: ```mermaid -graph LR +graph A[operation] B(title) C(summary) @@ -366,7 +366,7 @@ Some of the fields `components` object holds are: Here's a visual representation of the `components` object and its properties: ```mermaid -graph LR +graph A[components] B(schemas) C(category) From 6d7f6de9c3a1854812b13c37c57d5d5e7ba79c14 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 8 Nov 2023 20:44:16 +0530 Subject: [PATCH 16/22] Testing update to new link --- pages/docs/concepts/asyncapi-document/structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 0df7f23bf1f..e3cfafbe450 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -344,7 +344,7 @@ The purpose of the `components` object is to promote reusability and maintainabi Some of the fields `components` object holds are: -- `schemas`: An object to hold reusable [Schema Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#schemaObject). +- `schemas`: An object to hold reusable [Schema Object](../../reference/specification/v3.0.0#schemaObject). - `servers`: An object to hold reusable [Server Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverObject). - `channels`: An object to hold reusable [Channel Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelObject). - `operations`: An object to hold reusable [Operation Item Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). From 5366c0b3f719d6396937d51d0d547ad313212199 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 8 Nov 2023 20:46:58 +0530 Subject: [PATCH 17/22] test-2 --- pages/docs/concepts/asyncapi-document/structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index e3cfafbe450..e1f3ca39e53 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -344,7 +344,7 @@ The purpose of the `components` object is to promote reusability and maintainabi Some of the fields `components` object holds are: -- `schemas`: An object to hold reusable [Schema Object](../../reference/specification/v3.0.0#schemaObject). +- `schemas`: An object to hold reusable [Schema Object](../../reference/specification/latest#schemaObject). - `servers`: An object to hold reusable [Server Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverObject). - `channels`: An object to hold reusable [Channel Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelObject). - `operations`: An object to hold reusable [Operation Item Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). From 8def965651b6f05149e806a6fd1aef18f2c9946a Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 8 Nov 2023 21:23:28 +0530 Subject: [PATCH 18/22] Updating links to match V3 --- .../concepts/asyncapi-document/structure.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index e1f3ca39e53..8bb6dcdbb4b 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -344,25 +344,25 @@ The purpose of the `components` object is to promote reusability and maintainabi Some of the fields `components` object holds are: -- `schemas`: An object to hold reusable [Schema Object](../../reference/specification/latest#schemaObject). -- `servers`: An object to hold reusable [Server Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverObject). -- `channels`: An object to hold reusable [Channel Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelObject). -- `operations`: An object to hold reusable [Operation Item Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). -- `messages`: An object to hold reusable [Messages Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageObject). -- `securitySchemes`: An object to hold reusable [Security Scheme Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#securitySchemeObject). -- `serverVariables`: An object to hold reusable [Server Variable Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverVariableObject). -- `parameters`: Contains reusable [parameter objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#parameterObject) that can be used in various parts of the AsyncAPI document. -- `correlationIds`: An object to hold reusable [Correlation ID Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#correlationIdObject). -- `replies`: An object to hold reusable [Operation Reply Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationReplyObject). -- `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationReplyAddressObject). -- `externalDocs`: An object to hold reusable [External Documentation Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#externalDocumentationObject). -- `tags`: An object to hold reusable [Tag Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#tagObject). -- `operationTraits`: An object to hold reusable [Operation Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationTraitObject). -- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageTraitObject). -- `serverBindings`: An object to hold reusable [Server Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverBindingsObject). -- `channelBindings`: An object to hold reusable [Channel Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelBindingsObject). -- `operationBindings`: An object to hold reusable [Operation Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationBindingsObject). -- `messageBindings`: An object to hold reusable [Message Bindings Objects](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messageBindingsObject). +- `schemas`: An object to hold reusable [Schema Object](/pages/docs/reference/specification/latest#schemaObject). +- `servers`: An object to hold reusable [Server Objects](/pages/docs/reference/specification/latest#serverObject). +- `channels`: An object to hold reusable [Channel Objects](/pages/docs/reference/specification/latest#channelObject). +- `operations`: An object to hold reusable [Operation Item Objects](/pages/docs/reference/specification/latest#operationObject). +- `messages`: An object to hold reusable [Messages Objects](/pages/docs/reference/specification/latest#messageObject). +- `securitySchemes`: An object to hold reusable [Security Scheme Objects](/pages/docs/reference/specification/latest#securitySchemeObject). +- `serverVariables`: An object to hold reusable [Server Variable Objects](/pages/docs/reference/specification/latest#serverVariableObject). +- `parameters`: Contains reusable [parameter objects](/pages/docs/reference/specification/latest#parameterObject) that can be used in various parts of the AsyncAPI document. +- `correlationIds`: An object to hold reusable [Correlation ID Objects](/pages/docs/reference/specification/latest#correlationIdObject). +- `replies`: An object to hold reusable [Operation Reply Objects](/pages/docs/reference/specification/latest#operationReplyObject). +- `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](/pages/docs/reference/specification/latest#operationReplyAddressObject). +- `externalDocs`: An object to hold reusable [External Documentation Objects](/pages/docs/reference/specification/latest#externalDocumentationObject). +- `tags`: An object to hold reusable [Tag Objects](/pages/docs/reference/specification/latest#tagObject). +- `operationTraits`: An object to hold reusable [Operation Trait Objects](/pages/docs/reference/specification/latest#operationTraitObject). +- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects](/pages/docs/reference/specification/latest#messageTraitObject). +- `serverBindings`: An object to hold reusable [Server Bindings Objects](/pages/docs/reference/specification/latest#serverBindingsObject). +- `channelBindings`: An object to hold reusable [Channel Bindings Objects](/pages/docs/reference/specification/latest#channelBindingsObject). +- `operationBindings`: An object to hold reusable [Operation Bindings Objects](/pages/docs/reference/specification/latest#operationBindingsObject). +- `messageBindings`: An object to hold reusable [Message Bindings Objects](/pages/docs/reference/specification/latest#messageBindingsObject). Here's a visual representation of the `components` object and its properties: ```mermaid From 624f5453c542e29be17b6172f6e41ee3ad741773 Mon Sep 17 00:00:00 2001 From: Rohit Date: Wed, 8 Nov 2023 21:34:51 +0530 Subject: [PATCH 19/22] re-update links --- .../concepts/asyncapi-document/structure.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 8bb6dcdbb4b..cb8c83ebdd8 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -344,25 +344,25 @@ The purpose of the `components` object is to promote reusability and maintainabi Some of the fields `components` object holds are: -- `schemas`: An object to hold reusable [Schema Object](/pages/docs/reference/specification/latest#schemaObject). -- `servers`: An object to hold reusable [Server Objects](/pages/docs/reference/specification/latest#serverObject). -- `channels`: An object to hold reusable [Channel Objects](/pages/docs/reference/specification/latest#channelObject). -- `operations`: An object to hold reusable [Operation Item Objects](/pages/docs/reference/specification/latest#operationObject). -- `messages`: An object to hold reusable [Messages Objects](/pages/docs/reference/specification/latest#messageObject). -- `securitySchemes`: An object to hold reusable [Security Scheme Objects](/pages/docs/reference/specification/latest#securitySchemeObject). -- `serverVariables`: An object to hold reusable [Server Variable Objects](/pages/docs/reference/specification/latest#serverVariableObject). -- `parameters`: Contains reusable [parameter objects](/pages/docs/reference/specification/latest#parameterObject) that can be used in various parts of the AsyncAPI document. -- `correlationIds`: An object to hold reusable [Correlation ID Objects](/pages/docs/reference/specification/latest#correlationIdObject). -- `replies`: An object to hold reusable [Operation Reply Objects](/pages/docs/reference/specification/latest#operationReplyObject). -- `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](/pages/docs/reference/specification/latest#operationReplyAddressObject). -- `externalDocs`: An object to hold reusable [External Documentation Objects](/pages/docs/reference/specification/latest#externalDocumentationObject). -- `tags`: An object to hold reusable [Tag Objects](/pages/docs/reference/specification/latest#tagObject). -- `operationTraits`: An object to hold reusable [Operation Trait Objects](/pages/docs/reference/specification/latest#operationTraitObject). -- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects](/pages/docs/reference/specification/latest#messageTraitObject). -- `serverBindings`: An object to hold reusable [Server Bindings Objects](/pages/docs/reference/specification/latest#serverBindingsObject). -- `channelBindings`: An object to hold reusable [Channel Bindings Objects](/pages/docs/reference/specification/latest#channelBindingsObject). -- `operationBindings`: An object to hold reusable [Operation Bindings Objects](/pages/docs/reference/specification/latest#operationBindingsObject). -- `messageBindings`: An object to hold reusable [Message Bindings Objects](/pages/docs/reference/specification/latest#messageBindingsObject). +- `schemas`: An object to hold reusable [Schema Object](/docs/reference/specification/latest#schemaObject). +- `servers`: An object to hold reusable [Server Objects](/docs/reference/specification/latest#serverObject). +- `channels`: An object to hold reusable [Channel Objects](/docs/reference/specification/latest#channelObject). +- `operations`: An object to hold reusable [Operation Item Objects](/docs/reference/specification/latest#operationObject). +- `messages`: An object to hold reusable [Messages Objects](/docs/reference/specification/latest#messageObject). +- `securitySchemes`: An object to hold reusable [Security Scheme Objects](/docs/reference/specification/latest#securitySchemeObject). +- `serverVariables`: An object to hold 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 reusable [Correlation ID Objects](/docs/reference/specification/latest#correlationIdObject). +- `replies`: An object to hold reusable [Operation Reply Objects](/docs/reference/specification/latest#operationReplyObject). +- `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](/docs/reference/specification/latest#operationReplyAddressObject). +- `externalDocs`: An object to hold reusable [External Documentation Objects](docs/reference/specification/latest#externalDocumentationObject). +- `tags`: An object to hold reusable [Tag Objects](/docs/reference/specification/latest#tagObject). +- `operationTraits`: An object to hold 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 reusable [Server Bindings Objects](/docs/reference/specification/latest#serverBindingsObject). +- `channelBindings`: An object to hold reusable [Channel Bindings Objects](/docs/reference/specification/latest#channelBindingsObject). +- `operationBindings`: An object to hold reusable [Operation Bindings Objects](/docs/reference/specification/latest#operationBindingsObject). +- `messageBindings`: An object to hold reusable [Message Bindings Objects](/docs/reference/specification/latest#messageBindingsObject). Here's a visual representation of the `components` object and its properties: ```mermaid From b4e5b61675bcbd2a81132fde757bff60df121009 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 15 Nov 2023 15:47:34 +0100 Subject: [PATCH 20/22] Update structure.md --- .../concepts/asyncapi-document/structure.md | 414 +++++++++++------- 1 file changed, 258 insertions(+), 156 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index cb8c83ebdd8..70bd14bc56d 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -3,9 +3,10 @@ title: AsyncAPI document structure weight: 60 --- -The structure of an AsyncAPI document can be defined as a specific format in which the document of the specification is to be written and defined. The structure of an AsyncAPI document has certain fields that need to be followed and implemented. +The structure of an AsyncAPI document is defined in a specific format and must follow [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. + +## Root Elements -## Root Elements Root elements of an AsyncAPI document provide an overview of the API's characteristics and behaviour. 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 behaviour. ```mermaid @@ -24,12 +25,11 @@ A --> E A --> F ``` -### `Info` Object -The `info` object in an AsyncAPI document provides essential information about the API in the form of fields such as title, version, description, contact details and license. It serves as metadata that gives consumers a high-level understanding of the API's purpose and functionality. +### `info` field -The purpose of the `info` object is to provide descriptive and contact information about the specific API. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. +With the `info` field you provide essential information about the API in the form of fields such as title, version, description, contact details and license. It serves as metadata that gives consumers a high-level understanding of the API's purpose and functionality. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. -Some of the fields `info` object holds are: +Some of the fields `info` field holds are: - `title`: The title of the API. - `version`: The version of the API. @@ -40,9 +40,9 @@ Some of the fields `info` object holds are: - `tags`: A list of tags for application API documentation control. Tags can be used for logical grouping of applications. - `externalDocs`: Additional external documentation of the exposed API. -Here's a visual representation of the `info` object and its properties: +Here's a visual representation of the `info` field and its properties: ```mermaid -graph +graph LR B(info) C(title) D(version) @@ -51,7 +51,7 @@ graph G(contact) J(license) M(tags) - P((externalDocs)) + P(externalDocs) B --> C B --> D @@ -63,9 +63,8 @@ graph B --> P ``` -Below is an example of the `info` object in the AsyncAPI document: +Below is an example of the `info` field: ```yaml -asyncapi: 3.0.0 info: title: My Event-Driven API version: 1.0.0 @@ -87,12 +86,11 @@ info: url: https://example.com/docs ``` -### `Servers` Object -The `servers` object in an AsyncAPI document is a map of `server` objects that defines the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. +### `servers` field -The purpose of the `servers` object is to provide the necessary information for clients to connect to the message broker or server and participate in the message exchange or listen to the events. By defining multiple servers, the AsyncAPI document can accommodate different environments or deployment scenarios, such as production, staging, or development. +With the `servers` field you can provide a map of different servers that define the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. You can accommodate different environments or deployment scenarios, such as production, staging, or development. -Some of the fields `servers` object holds for each server object are: +Some of the fields of individual `servers` field are: - `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). @@ -108,7 +106,7 @@ Some of the fields `servers` object holds for each server object are: Here's a visual representation of the `server` object and its properties: ```mermaid -graph +graph LR A[server] B(host) C(pathname) @@ -117,10 +115,11 @@ graph F(description) G(title) H(summary) - I(security) - J(tags) - K(externalDocs) - L(bindings) + I(variables) + J(security) + K(tags) + L(externalDocs) + M(bindings) A --> B A --> C @@ -133,20 +132,23 @@ graph A --> J A --> K A --> L + A --> M ``` -Here's a code example of the servers object with multiple servers in an AsyncAPI document: +Below is an example of the `servers` field with multiple servers: ```yaml servers: - - host: rabbitmq.in.mycompany.com:5672 - pathname: /production + production: + host: rabbitmq.in.mycompany.com:5672 + pathname: /v1 protocol: amqp - protocolVersion: 1.0 + protocolVersion: "1.0" description: Production RabbitMQ broker (uses the `production` vhost). title: Production Server summary: Production environment server security: - - apiKey: [] + - type: http + scheme: bearer tags: - name: production description: Production environment @@ -157,15 +159,18 @@ servers: amqp: exchange: my-exchange queue: my-queue - - host: rabbitmq.in.mycompany.com:5672 - pathname: /staging + staging: + host: rabbitmq.in.mycompany.com:5672 + pathname: /v1 protocol: amqp - protocolVersion: 1.0 + protocolVersion: "1.0" description: Staging RabbitMQ broker (uses the `staging` vhost). title: Staging Server summary: Staging environment server security: - - apiKey: [] + - type: apiKey + in: user + description: Provide your API key as the user and leave the password empty. tags: - name: staging description: Staging environment @@ -178,27 +183,26 @@ servers: queue: my-queue ``` -### `Channels` Object -The `channels` object in an AsyncAPI document holds all the individual `channel` object definitions that the application must use during runtime. The `channels` represent the communication pathways through which messages are exchanged. The `channel` object describes a shared communication channel. +### `channels` field -The purpose of the `channels` object is to provide a structured way to define the messaging patterns and topics within the API. It allows API developers to specify the available channels, their purpose, 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 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. -Some of the fields `channels` object holds for each channel object are: +Some of the fields of individual `channels` field are: - `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. - `title`: A human-readable title for the channel. - `summary`: A short yet brief 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` Object. +- `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. - `parameters`: A map of the parameters included in the channel address. - `tags`: A list of tags for logical grouping of 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` object and its properties: +Here's a visual representation of the `channels` field and its properties: ```mermaid -graph +graph LR A[channel] B(address) C(title) @@ -221,41 +225,41 @@ graph A --> R ``` -Here's a code example illustrating the structure of the channels object in an AsyncAPI document: +Below is an example of of the `channels` field with one channel: ```yaml -address: 'users.{userId}' -title: Users channel -description: This channel is used to exchange messages about user events. -messages: - userSignedUp: - $ref: '#/components/messages/userSignedUp' - userCompletedOrder: - $ref: '#/components/messages/userCompletedOrder' -parameters: - userId: - $ref: '#/components/parameters/userId' -servers: - - $ref: '#/servers/rabbitmqInProd' - - $ref: '#/servers/rabbitmqInStaging' -bindings: - amqp: - is: queue - queue: - exclusive: true -tags: - - name: user - description: User-related messages -externalDocs: - description: 'Find more info here' - url: 'https://example.com' +channels: + user: + address: 'users.{userId}' + title: Users channel + description: This channel is used to exchange messages about user events. + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' + parameters: + userId: + $ref: '#/components/parameters/userId' + servers: + - $ref: '#/servers/production' + bindings: + amqp: + is: queue + queue: + exclusive: true + tags: + - name: user + description: User-related messages + externalDocs: + description: 'Find more info here' + url: 'https://example.com' ``` -### `Operations` Object -The `operations` object holds a dictionary with all the operations the application must implement. The purpose of the `operations` object is to provide a clear and structured definition of the operations that an application must support within an event-driven API. +### `operations` field -The `operations` object is located within the AsyncAPI document and is separate from the components/operations section, which is used for optional or additional operations that may or may not be implemented by the application. +With the `operations` field you can describe all the operations the application performs. Use it to provide a clear and structured definition of the operations. Specify if your application is sending or receiving messages, and what is the purpose of such operation. -Some of the fields `operations` object holds for each `operation` object are: +Some of the fields of individual `operations` field are: - `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. @@ -270,9 +274,9 @@ Some of the fields `operations` object holds for each `operation` object are: - `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 request-reply operation. -Here's a visual representation of the `operations` object and its properties: +Here's a visual representation of the `operations` field and its properties: ```mermaid -graph +graph LR A[operation] B(title) C(summary) @@ -303,46 +307,51 @@ graph L --> N ``` -Here's a code example illustrating the structure of the `operations` object in an AsyncAPI document: +Below is an example of of the `operations` field with one operation: ```yaml -title: User sign up -summary: Action to sign a user up. -description: A longer description -channel: - $ref: '#/channels/userSignup' -action: send -security: - - petstore_auth: - - write:pets - - read:pets -tags: - - name: user - - name: signup - - name: register -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -messages: - - $ref: '#/components/messages/userSignedUp' -reply: - address: - location: '$message.header#/replyTo' - channel: - $ref: '#/channels/userSignupReply' - messages: - - $ref: '#/components/messages/userSignedUpReply' +operations: + sendUserSignUp: + action: send + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/user' + security: + - type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + availableScopes: + 'subscribe:auth_revocations': Scope required for authorization revocation topic + scopes: + - 'subscribe:auth_revocations' + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: "#/components/operationTraits/kafka" + messages: + - $ref: '#/components/messages/userSignedUp' + reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/channels/userSignupReply/messages/userSignedUpReply' ``` -### `Components` Object -The `components` object in an AsyncAPI document serves as a container for reusable structures or definitions that can be used across different parts of the AsyncAPI document. It allows you to define and manage common elements such as message schemas, security schemes, headers, and other custom components that are referenced throughout the API specification. +### `components` field -All objects defined within the `components` object will not affect the specific API unless they are explicitly referenced from properties outside the components object. +With `components` field you can define a set of reusable structures or definitions that can be used across different parts of your document. Information provide under `components` are not part of the API unless they are explicitly referenced from properties outside the `components` field. Use it to not repeat yourself and improve maintainability of the document. -The purpose of the `components` object is to promote reusability and maintainability of the AsyncAPI document. By centralizing common definitions in the components section, you can avoid duplicating code and ensure consistency across different parts of the API specification. It also enhances the readability and understandability of the document by providing a clear separation of concerns. - -Some of the fields `components` object holds are: +Some of the fields of individual `channels` field are: - `schemas`: An object to hold reusable [Schema Object](/docs/reference/specification/latest#schemaObject). - `servers`: An object to hold reusable [Server Objects](/docs/reference/specification/latest#serverObject). @@ -351,7 +360,7 @@ Some of the fields `components` object holds are: - `messages`: An object to hold reusable [Messages Objects](/docs/reference/specification/latest#messageObject). - `securitySchemes`: An object to hold reusable [Security Scheme Objects](/docs/reference/specification/latest#securitySchemeObject). - `serverVariables`: An object to hold 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. +- `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 reusable [Correlation ID Objects](/docs/reference/specification/latest#correlationIdObject). - `replies`: An object to hold reusable [Operation Reply Objects](/docs/reference/specification/latest#operationReplyObject). - `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](/docs/reference/specification/latest#operationReplyAddressObject). @@ -364,38 +373,55 @@ Some of the fields `components` object holds are: - `operationBindings`: An object to hold reusable [Operation Bindings Objects](/docs/reference/specification/latest#operationBindingsObject). - `messageBindings`: An object to hold reusable [Message Bindings Objects](/docs/reference/specification/latest#messageBindingsObject). -Here's a visual representation of the `components` object and its properties: +Here's a visual representation of the `components` field and its properties: ```mermaid -graph +graph LR A[components] B(schemas) - C(category) - D(tag) + C(messages) + D(serverVariables) + E(replies) + F(replyAddresses) G(servers) - H(development) - I(serverVariables) + H(operations) + I(securitySchemes) + J(tags) + K(operationTraits) L(channels) - P(messages) + M(serverBindings) + N(channelBindings) + O(operationBindings) + R(messageBindings) + P(externalDocs) U(parameters) W(correlationIds) Y(messageTraits) A --> B - B --> C - B --> D + A --> C + A --> H A --> G - G --> H - H --> I + A --> D A --> L - A --> P 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 ``` Here's a code example of the components object in an AsyncAPI document: ```yaml components: + schemas: Category: type: object @@ -403,70 +429,111 @@ components: id: type: integer format: int64 - name: - type: string - Tag: - type: object - properties: - id: - type: integer - format: int64 - name: - type: string AvroExample: schemaFormat: application/vnd.apache.avro+json;version=1.9.0 schema: $ref: 'path/to/user-create.avsc/#UserCreate' + servers: development: - url: "{stage}.in.mycompany.com:{port}" - description: RabbitMQ broker + host: '{stage}.in.mycompany.com' protocol: amqp - protocolVersion: 0-9-1 + description: RabbitMQ broker + bindings: + $ref: '#/components/serverBindings/devAmqp' variables: stage: - $ref: "#/components/serverVariables/stage" - port: - $ref: "#/components/serverVariables/port" + $ref: '#/components/serverVariables/stage' + security: + - $ref: '#/components/securitySchemes/oauth' + serverVariables: stage: default: demo description: This value is assigned by the service provider, in this example `mycompany.com` - port: - enum: [5671, 5672] - default: 5672 + channels: + user: + address: 'users.{userId}' + title: Users channel + description: This channel is used to exchange messages about user events. + messages: + userSignedUp: + $ref: '#/components/messages/userSignUp' + parameters: + userId: + $ref: '#/components/parameters/userId' + servers: + - $ref: '#/components/servers/development' + bindings: + $ref: '#/components/channelBindings/user' + tags: + - $ref: '#/components/tags/user' + externalDocs: + $ref: '#/components/externalDocs/infoDocs' + messages: userSignUp: summary: Action to sign a user up. - description: | - Multiline description of what this action does. - Here you have another line. - tags: - - name: user - - name: signup - headers: - type: object - properties: - applicationInstanceId: - description: Unique identifier for a given instance of the publishing application - type: string + traits: + - $ref: '#/components/messageTraits/commonHeaders' payload: - type: object - properties: - user: - $ref: "#/components/schemas/userCreate" - signup: - $ref: "#/components/schemas/signup" + $ref: '#/components/schemas/Category' + correlationId: + $ref: '#/components/correlationIds/default' + bindings: + $ref: '#/components/messageBindings/user' + parameters: userId: description: Id of the user. - schema: - type: string + correlationIds: default: description: Default Correlation ID location: $message.header#/correlationId + + operations: + sendUserSignUp: + action: send + title: User sign up + bindings: + $ref: '#/components/operationBindings/sendUser' + traits: + - $ref: '#/components/operationTraits/binding' + reply: + $ref: '#/components/replies/signupReply' + + replies: + signupReply: + address: + $ref: '#/components/replyAddresses/signupReply' + channel: + $ref: '#/channels/userSignupReply' + + replyAddresses: + signupReply: + location: '$message.header#/replyTo' + + + securitySchemes: + oauth: + type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + availableScopes: + 'subscribe:auth_revocations': Scope required for authorization revocation topic + scopes: + - 'subscribe:auth_revocations' + + operationTraits: + binding: + bindings: + amqp: + ack: false + messageTraits: commonHeaders: headers: @@ -476,4 +543,39 @@ components: type: integer minimum: 0 maximum: 100 -``` \ No newline at end of file + + tags: + user: + name: user + description: User-related messages + + externalDocs: + infoDocs: + url: https://example.com/docs + description: 'Find more info here' + + serverBindings: + devAmqp: + amqp: + exchange: my-exchange + queue: my-queue + + channelBindings: + user: + amqp: + is: queue + queue: + exclusive: true + + operationBindings: + sendUser: + amqp: + ack: false + + messageBindings: + user: + amqp: + contentEncoding: gzip + messageType: 'user.signup' + bindingVersion: '0.2.0' +``` From d45be6da7348a15b8bfde0281af7be22dec5b357 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Wed, 15 Nov 2023 16:36:52 -0800 Subject: [PATCH 21/22] Delete duplicate _section.md --- pages/docs/concepts/asyncapi-document/_section.md | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 pages/docs/concepts/asyncapi-document/_section.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md deleted file mode 100644 index 05a0c710216..00000000000 --- a/pages/docs/concepts/asyncapi-document/_section.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'AsyncAPI Document' -weight: 50 ---- From c8ca885f1569b3cd619fb5e58cc878ab70a68a1c Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Wed, 15 Nov 2023 17:28:50 -0800 Subject: [PATCH 22/22] tw editorial fixes --- .../concepts/asyncapi-document/structure.md | 80 +++++++++---------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md index 70bd14bc56d..6beb3d9b865 100644 --- a/pages/docs/concepts/asyncapi-document/structure.md +++ b/pages/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 [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. +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. -## Root Elements +## Root elements -Root elements of an AsyncAPI document provide an overview of the API's characteristics and behaviour. 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 behaviour. +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. ```mermaid graph @@ -27,18 +27,18 @@ A --> F ### `info` field -With the `info` field you provide essential information about the API in the form of fields such as title, version, description, contact details and license. It serves as metadata that gives consumers a high-level understanding of the API's purpose and functionality. It helps developers, architects, and other stakeholders quickly identify and comprehend the API's characteristics without diving into the technical details. Plus, `info` is a required component of the AsyncAPI document and often the first point of reference for users exploring the API documentation. +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. -Some of the fields `info` field holds are: +The `info` field encompasses various fields such as: -- `title`: The title of the API. -- `version`: The version of the API. -- `description`: A brief description explaining the purpose and features of the API. -- `termsOfService`: The URL or document specifying the terms of service for using the API. -- `contact`: Contact information for the owner or maintainer of the API, including name, email, and URL. -- `license`: Information about the license under which the API is provided, including name and URL. -- `tags`: A list of tags for application API documentation control. Tags can be used for logical grouping of applications. -- `externalDocs`: Additional external documentation of the exposed API. +- `title`: API title. +- `version`: API version. +- `description`: Brief description describing 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 @@ -72,7 +72,7 @@ info: termsOfService: https://example.com/terms-of-service contact: name: Rohit - email: rohit@asyncapi.com + email: rohitwashere@asyncapi.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -88,7 +88,7 @@ info: ### `servers` field -With the `servers` field you can provide a map of different servers that define the network endpoints or brokers that applications can connect to for exchanging messages. It specifies the details necessary to establish a connection, such as the protocol, host, port, and additional connection options. You can accommodate different environments or deployment scenarios, such as production, staging, or development. +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. Some of the fields of individual `servers` field are: @@ -185,9 +185,9 @@ 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, 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. -Some of the fields of individual `channels` field are: +Key components within the `channels` field include: - `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. @@ -257,9 +257,9 @@ channels: ### `operations` field -With the `operations` field you can describe all the operations the application performs. Use it to provide a clear and structured definition of the operations. Specify if your application is sending or receiving messages, and what is the purpose of such operation. +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. -Some of the fields of individual `operations` field are: +Key components within the `operations` field include: - `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. @@ -272,7 +272,7 @@ Some of the fields of individual `operations` field are: - `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 request-reply 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 @@ -349,29 +349,29 @@ operations: ### `components` field -With `components` field you can define a set of reusable structures or definitions that can be used across different parts of your document. Information provide under `components` are not part of the API unless they are explicitly referenced from properties outside the `components` field. Use it to not repeat yourself and improve maintainability of the document. +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. -Some of the fields of individual `channels` field are: +Key components of the `channels` field include: -- `schemas`: An object to hold reusable [Schema Object](/docs/reference/specification/latest#schemaObject). -- `servers`: An object to hold reusable [Server Objects](/docs/reference/specification/latest#serverObject). -- `channels`: An object to hold reusable [Channel Objects](/docs/reference/specification/latest#channelObject). -- `operations`: An object to hold reusable [Operation Item Objects](/docs/reference/specification/latest#operationObject). -- `messages`: An object to hold reusable [Messages Objects](/docs/reference/specification/latest#messageObject). -- `securitySchemes`: An object to hold reusable [Security Scheme Objects](/docs/reference/specification/latest#securitySchemeObject). -- `serverVariables`: An object to hold reusable [Server Variable Objects](/docs/reference/specification/latest#serverVariableObject). +- `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 reusable [Correlation ID Objects](/docs/reference/specification/latest#correlationIdObject). -- `replies`: An object to hold reusable [Operation Reply Objects](/docs/reference/specification/latest#operationReplyObject). -- `replyAddresses`: An object to hold reusable [Operation Reply Address Objects](/docs/reference/specification/latest#operationReplyAddressObject). -- `externalDocs`: An object to hold reusable [External Documentation Objects](docs/reference/specification/latest#externalDocumentationObject). -- `tags`: An object to hold reusable [Tag Objects](/docs/reference/specification/latest#tagObject). -- `operationTraits`: An object to hold reusable [Operation Trait Objects](/docs/reference/specification/latest#operationTraitObject). +- `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 reusable [Server Bindings Objects](/docs/reference/specification/latest#serverBindingsObject). -- `channelBindings`: An object to hold reusable [Channel Bindings Objects](/docs/reference/specification/latest#channelBindingsObject). -- `operationBindings`: An object to hold reusable [Operation Bindings Objects](/docs/reference/specification/latest#operationBindingsObject). -- `messageBindings`: An object to hold reusable [Message Bindings Objects](/docs/reference/specification/latest#messageBindingsObject). +- `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 @@ -450,7 +450,7 @@ components: serverVariables: stage: default: demo - description: This value is assigned by the service provider, in this example `mycompany.com` + description: This value is assigned by the service provider in this example of `mycompany.com` channels: user: