The structure of an AsyncAPI document is defined in a specific format and must follow the AsyncAPI specification. 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 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.
info field
The info field in an API document offers crucial metadata, including the API's title, version, description, contact details, and license. This field provides a comprehensive overview of the API, aiding developers, architects, and other stakeholders in quickly grasping its purpose and capabilities. As a mandatory element of the AsyncAPI specification, the info field often serves as the initial reference point for users navigating the API documentation.
The info field encompasses various fields such as:
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:
Below is an example of the info field:
1info:
2 title: My Event-Driven API
3 version: 1.0.0
4 description: This API provides real-time event streaming capabilities.
5 termsOfService: https://example.com/terms-of-service
6 contact:
7 name: Rohit
8 email: rohitwashere@asyncapi.com
9 license:
10 name: Apache 2.0
11 url: https://www.apache.org/licenses/LICENSE-2.0.html
12 tags:
13 - name: Events
14 description: APIs related to event streaming
15 - name: Authentication
16 description: APIs for authentication and authorization
17 externalDocs:
18 description: Additional documentation
19 url: https://example.com/docsservers field
The servers field allows you to detail a range of servers, outlining the network endpoints or message brokers to which applications can connect. That field includes vital connection information like protocol, host, port, and other options, facilitating connectivity across various environments such as production, staging, or development.
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).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 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:
Below is an example of the servers field with multiple servers:
1servers:
2 production:
3 host: rabbitmq.in.mycompany.com:5672
4 pathname: /v1
5 protocol: amqp
6 protocolVersion: "1.0"
7 description: Production RabbitMQ broker (uses the `production` vhost).
8 title: Production Server
9 summary: Production environment server
10 security:
11 - type: http
12 scheme: bearer
13 tags:
14 - name: production
15 description: Production environment
16 externalDocs:
17 description: Additional documentation for the production server
18 url: https://example.com/docs/production
19 bindings:
20 amqp:
21 exchange: my-exchange
22 queue: my-queue
23 staging:
24 host: rabbitmq.in.mycompany.com:5672
25 pathname: /v1
26 protocol: amqp
27 protocolVersion: "1.0"
28 description: Staging RabbitMQ broker (uses the `staging` vhost).
29 title: Staging Server
30 summary: Staging environment server
31 security:
32 - type: apiKey
33 in: user
34 description: Provide your API key as the user and leave the password empty.
35 tags:
36 - name: staging
37 description: Staging environment
38 externalDocs:
39 description: Additional documentation for the staging server
40 url: https://example.com/docs/staging
41 bindings:
42 amqp:
43 exchange: my-exchange
44 queue: my-queuechannels 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.
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.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$refpointers 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 theserversfield.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 field and its properties:
Below is an example of of the channels field with one channel:
1channels:
2 user:
3 address: 'users.{userId}'
4 title: Users channel
5 description: This channel is used to exchange messages about user events.
6 messages:
7 userSignedUp:
8 $ref: '#/components/messages/userSignedUp'
9 userCompletedOrder:
10 $ref: '#/components/messages/userCompletedOrder'
11 parameters:
12 userId:
13 $ref: '#/components/parameters/userId'
14 servers:
15 - $ref: '#/servers/production'
16 bindings:
17 amqp:
18 is: queue
19 queue:
20 exclusive: true
21 tags:
22 - name: user
23 description: User-related messages
24 externalDocs:
25 description: 'Find more info here'
26 url: 'https://example.com'operations field
The operations field is used to comprehensively outline the various operations performed by the application. It offers a clear, structured description, detailing whether the application sends or receives messages and the specific purpose of each operation.
Key components within the operations field include:
action: Usesendtype when it's expected that the application will send a message to the given channel, andreceivetype when the application should expect to receive messages from the given channel.channel: A$refpointer 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.bindingsA map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.traits: A list of traits to apply to the operation object.messages: A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation.reply: The definition of the reply in a reply/request operation.
Here's a visual representation of the operations field and its properties:
Below is an example of of the operations field with one operation:
1operations:
2 sendUserSignUp:
3 action: send
4 title: User sign up
5 summary: Action to sign a user up.
6 description: A longer description
7 channel:
8 $ref: '#/channels/user'
9 security:
10 - type: oauth2
11 description: The oauth security descriptions
12 flows:
13 clientCredentials:
14 tokenUrl: 'https://example.com/api/oauth/dialog'
15 availableScopes:
16 'subscribe:auth_revocations': Scope required for authorization revocation topic
17 scopes:
18 - 'subscribe:auth_revocations'
19 tags:
20 - name: user
21 - name: signup
22 - name: register
23 bindings:
24 amqp:
25 ack: false
26 traits:
27 - $ref: "#/components/operationTraits/kafka"
28 messages:
29 - $ref: '#/components/messages/userSignedUp'
30 reply:
31 address:
32 location: '$message.header#/replyTo'
33 channel:
34 $ref: '#/channels/userSignupReply'
35 messages:
36 - $ref: '#/channels/userSignupReply/messages/userSignedUpReply'components field
The components field allows for the definition of reusable structures or definitions applicable across various sections of your document. Items detailed within components only become part of the API when explicitly referenced by properties external to this field. Utilize it to avoid repetition and enhance the document's maintainability.
Key components of the components field include:
schemas: An object to hold the reusable Schema Object.servers: An object to hold the reusable Server Objects.channels: An object to hold the reusable Channel Objects.operations: An object to hold the reusable Operation Item Objects.messages: An object to hold the reusable Messages Objects.securitySchemes: An object to hold the reusable Security Scheme Objects.serverVariables: An object to hold the 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 the reusable Correlation ID Objects.replies: An object to hold the reusable Operation Reply Objects.replyAddresses: An object to hold the reusable Operation Reply Address Objects.externalDocs: An object to hold the reusable External Documentation Objects.tags: An object to hold the reusable Tag Objects.operationTraits: An object to hold the reusable Operation Trait Objects.messageTraits: Represents common traits or characteristics that can be applied to messages or hold reusable Message Trait Objects.serverBindings: An object to hold the reusable Server Bindings Objects.channelBindings: An object to hold the reusable Channel Bindings Objects.operationBindings: An object to hold the reusable Operation Bindings Objects.messageBindings: An object to hold the reusable Message Bindings Objects.
Here's a visual representation of the components field and its properties:
Here's a code example of the components object in an AsyncAPI document:
1components:
2
3 schemas:
4 Category:
5 type: object
6 properties:
7 id:
8 type: integer
9 format: int64
10 AvroExample:
11 schemaFormat: application/vnd.apache.avro+json;version=1.9.0
12 schema:
13 $ref: 'path/to/user-create.avsc/#UserCreate'
14
15 servers:
16 development:
17 host: '{stage}.in.mycompany.com'
18 protocol: amqp
19 description: RabbitMQ broker
20 bindings:
21 $ref: '#/components/serverBindings/devAmqp'
22 variables:
23 stage:
24 $ref: '#/components/serverVariables/stage'
25 security:
26 - $ref: '#/components/securitySchemes/oauth'
27
28 serverVariables:
29 stage:
30 default: demo
31 description: This value is assigned by the service provider in this example of `mycompany.com`
32
33 channels:
34 user:
35 address: 'users.{userId}'
36 title: Users channel
37 description: This channel is used to exchange messages about user events.
38 messages:
39 userSignedUp:
40 $ref: '#/components/messages/userSignUp'
41 parameters:
42 userId:
43 $ref: '#/components/parameters/userId'
44 servers:
45 - $ref: '#/components/servers/development'
46 bindings:
47 $ref: '#/components/channelBindings/user'
48 tags:
49 - $ref: '#/components/tags/user'
50 externalDocs:
51 $ref: '#/components/externalDocs/infoDocs'
52
53 messages:
54 userSignUp:
55 summary: Action to sign a user up.
56 traits:
57 - $ref: '#/components/messageTraits/commonHeaders'
58 payload:
59 $ref: '#/components/schemas/Category'
60 correlationId:
61 $ref: '#/components/correlationIds/default'
62 bindings:
63 $ref: '#/components/messageBindings/user'
64
65 parameters:
66 userId:
67 description: Id of the user.
68
69 correlationIds:
70 default:
71 description: Default Correlation ID
72 location: $message.header#/correlationId
73
74 operations:
75 sendUserSignUp:
76 action: send
77 title: User sign up
78 bindings:
79 $ref: '#/components/operationBindings/sendUser'
80 traits:
81 - $ref: '#/components/operationTraits/binding'
82 reply:
83 $ref: '#/components/replies/signupReply'
84
85 replies:
86 signupReply:
87 address:
88 $ref: '#/components/replyAddresses/signupReply'
89 channel:
90 $ref: '#/channels/userSignupReply'
91
92 replyAddresses:
93 signupReply:
94 location: '$message.header#/replyTo'
95
96
97 securitySchemes:
98 oauth:
99 type: oauth2
100 description: The oauth security descriptions
101 flows:
102 clientCredentials:
103 tokenUrl: 'https://example.com/api/oauth/dialog'
104 availableScopes:
105 'subscribe:auth_revocations': Scope required for authorization revocation topic
106 scopes:
107 - 'subscribe:auth_revocations'
108
109 operationTraits:
110 binding:
111 bindings:
112 amqp:
113 ack: false
114
115 messageTraits:
116 commonHeaders:
117 headers:
118 type: object
119 properties:
120 my-app-header:
121 type: integer
122 minimum: 0
123 maximum: 100
124
125 tags:
126 user:
127 name: user
128 description: User-related messages
129
130 externalDocs:
131 infoDocs:
132 url: https://example.com/docs
133 description: 'Find more info here'
134
135 serverBindings:
136 devAmqp:
137 amqp:
138 exchange: my-exchange
139 queue: my-queue
140
141 channelBindings:
142 user:
143 amqp:
144 is: queue
145 queue:
146 exclusive: true
147
148 operationBindings:
149 sendUser:
150 amqp:
151 ack: false
152
153 messageBindings:
154 user:
155 amqp:
156 contentEncoding: gzip
157 messageType: 'user.signup'
158 bindingVersion: '0.2.0'