Server variables

The server's URL consists of the host and pathname fields. These values are not always known when you design your system. AsyncAPI enables you to construct dynamic URLs while enhancing the flexibility and maintainability of your AsyncAPI documents. These dynamic values (variables) are placeholders for values you can replace during runtime. You can easily manage multiple endpoints, handling various server configurations and environments.

Add variables

You can add variables to server.host and server.pathname by adding a variable between curly braces like {braces}. Next, you use server.variables to provide definitions of your variables. Finally, leverage components.serverVariables to enable reusable variable definitions across multiple servers.

The diagram below describes how to use reusable variables in AsyncAPI.

First, configure the variables in host and/or pathname. Next, define reusable variables in components.serverVariables. Finally, ensure that your server.variables from the server reference definitions in the components.serverVariables uses $ref.

Servers section

Define the servers section in your AsyncAPI document, including the host and pathname for your API servers. Use placeholders enclosed in curly braces to represent the variables in the server. For example:

1servers:
2  production:
3    host: '{subdomain}.example.com:{port}'
4    pathname: '/{version}
5    variables:
6      subdomain:
7        enum:
8          - development
9          - staging
10          - production
11      port:
12        default: '8080'
13      version:
14        enum:
15          - v1
16          - v2

serverVariables section

Define the components.serverVariables section in your AsyncAPI document. For each variable used in the server host or pathname, provide a default value and an optional description to avoid repeating the variable definitions. For example:

1components:
2  serverVariables:
3    subdomain:
4      enum:
5        - development
6        - staging
7        - production
8      default: development
9    port:
10      default: '8080'
11    version:
12      enum:
13        - v1
14        - v2

Define domain and port variables

Use components.serverVariables in your server using the Reference Object to avoid repeating information:

1    variables:
2      subdomain:
3        $ref: '#/components/serverVariables/subdomain'

Here's the complete AsyncAPI document with the servers' variables for the host field:

1asyncapi: 3.0.0
2info:
3  title: Example API
4  version: '1.0.0'
5servers:
6  production:
7    host: '{subdomain}.example.com:{port}'
8    pathname: '/{version}'
9    protocol: amqp
10    variables:
11      subdomain:
12        $ref: '#/components/serverVariables/subdomain'
13      port:
14        $ref: '#/components/serverVariables/port'
15      version:
16        $ref: '#/components/serverVariables/version'
17  development:
18    host: '{subdomain}.dev.example.com:{port}'
19    pathname: /v1
20    protocol: amqp
21    variables:
22      subdomain:
23        $ref: '#/components/serverVariables/subdomain'
24      port:
25        $ref: '#/components/serverVariables/port'
26      version:
27        $ref: '#/components/serverVariables/version'
28components:
29  serverVariables:
30    subdomain:
31      enum:
32        - development
33        - staging
34        - production
35      default: development
36    port:
37      default: '8080'
38    version:
39      enum:
40        - v1
41        - v2