An AsyncAPI document structure must follow a specific format defined by the AsyncAPI specification. It has mandatory and optional fields.
Root elements
Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements define metadata, channels, components, and more.
info field
The info field is a mandatory element of the AsyncAPI specification that serves as the initial reference point for users navigating the API documentation and helping developers, architects, and other stakeholders quickly grasp the API's purpose and capabilities. This field contains essential metadata, including:
title: API title.version: API version.description: Brief description of the API's purpose and features.termsOfService: URL or document specifying the API's terms of service.contact: Contact information of the API's owner or maintainer (name, email, and URL).license: API's license information, including name and URL.tags: A list of keywords to organize and categorize API documentation. They are also used to group applications logically.externalDocs: Links to additional, external documentation related to the API.
Below is an example of the info field:
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 details various servers, including network endpoints or message brokers to which applications can connect. This field includes connection information like protocol, host, port, and other options, enabling connectivity across different environments like production, staging, or development.
The individual servers field contains the following properties:
host: The server hostname. It may include the port.protocol: The protocol or messaging protocol that is used by the server (for example, AMQP, MQTT, WebSocket).protocolVersion: The protocol version used for the connection.pathname: The path to a resource in the host.description: A string describing the server.title: A human-friendly title for the server.summary: A brief overview of the server.security: A declaration of security schemes supported by the server.tags: a list of keywords to logically group and categorize servers.externalDocs: Additional external documentation for this server.bindings: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.
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 channels the application communicates with during runtime. For each channel, you can specify the purpose, address, and expected message formats so that API consumers can understand the supported message-based interactions and the corresponding data models.
The individual channels field contains the following properties:
address: A string representation of this channel's address.messages: A map of all messages sent to this channel by any application.title: A human-readable title for the channel.summary: A summary of the channel.description: A description of the channel, providing additional context and details of the message.servers: An array of$refpointers to the server definitions for this channel. If servers are absent or empty, this channel must be available on all servers defined in theserversfield.parameters: A map of the parameters included in the channel address.tags: a list of keywords to logically group channels.externalDocs: Additional external documentation for this channel.bindings: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.
Below is an example 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.comoperations field
The operations field specifies operations the application can perform. It offers a clear and structured description detailing whether the application sends or receives messages and the specific purpose of each operation.
The individual operations field contains the following properties:
action: Usesendwhen the application expects to send a message to a channel andreceivewhen it expects to receive messages from a channel.channel: Arefpointer to the channel definition that ensures the operation execution.title: A human-friendly title for the operation.summary: A brief overview of the operation.description: A detailed explanation of the operation.security: A declaration of security schemes associated with the operation.tags: a list of keywords to logically group and categorize operations.externalDocs: Additional external documentation for this operation.bindings: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.traits: A list of traits to apply to the operation object.messages: A list of$refpointers to the supported Message Objects that this operation can process.reply: The definition of the reply in a reply/request operation.
Below is an example of 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 lets you define reusable structures or definitions across your document. Items in components only become part of the API when explicitly referenced by properties outside this field, so you can use it to avoid repetition and improve maintainability.
The components field contains the following properties:
schemas: An object to hold the reusable Schema Object.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 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