AsyncAPI Logo
On this page

AsyncAPI document structure

Found an error? Have a suggestion?Edit this page on GitHub

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.

Loading diagram...

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/docs

servers 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-queue

channels 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 $ref pointers to the server definitions for this channel. If servers are absent or empty, this channel must be available on all servers defined in the servers field.
  • parameters: A map of the parameters included in the channel address.
  • tags: a list of 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.com

operations 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: Use send when the application expects to send a message to a channel and receive when it expects to receive messages from a channel.
  • channel: A ref pointer to the channel definition that ensures the operation execution.
  • title: A human-friendly title for the operation.
  • summary: A brief overview of the operation.
  • description: A detailed explanation of the operation.
  • security: A declaration of security schemes associated with the operation.
  • tags: a list of keywords to logically group and categorize operations.
  • externalDocs: Additional external documentation for this operation.
  • bindings: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
  • traits: A list of traits to apply to the operation object.
  • messages: A list of $ref pointers 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:

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
Was this helpful?
Help us improve the docs by adding your contribution.
OR
Github:AsyncAPICreate Issue on GitHub