From 672b1bc5d5261b7511c4b6cd9f1f074a5821111c Mon Sep 17 00:00:00 2001 From: kakabisht Date: Sun, 10 Dec 2023 00:00:19 +0530 Subject: [PATCH 1/3] Add variable urls --- .../asyncapi-document/variable-url.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/variable-url.md diff --git a/pages/docs/concepts/asyncapi-document/variable-url.md b/pages/docs/concepts/asyncapi-document/variable-url.md new file mode 100644 index 00000000000..11ccbb6afa5 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/variable-url.md @@ -0,0 +1,105 @@ +--- +title: Variable URL +weight: 275 +--- + +Servers benefit from a defined base URL and rules for URL variables. You can easily manage multiple endpoints, handling various server configurations and environments. + +URL variables are placeholders for values you can replace during runtime. AsyncAPI enables you to construct dynamic URLs while enhancing the flexibility and maintainability of your AsyncAPI documents. + +## Add dynamic variables + +Use the `server.url` and `server.variables` to add variables to a server URL. Leverage `components.serverVariables` to enable reusable variable definitions across multiple servers. + +The diagram below describes how to use variable urls in AsyncAPI. + +```mermaid +graph TD + + A[AsyncAPI Server] + B[Components] + C[Server URL] + +style A fill:#47BCEE,stroke:#47BCEE; +style B fill:#47BCEE,stroke:#47BCEE; +style C fill:#47BCEE,stroke:#47BCEE; + + B -->|Defines serverVariables| C + C -->|Reusable variables| A +``` + +### Servers section + +Define the servers section in your AsyncAPI document, and include the base URLs for your API servers. Use placeholders enclosed in curly braces {} to represent the variables in the server URL. For example: + +```yaml +servers: + production: + url: 'https://{subdomain}.example.com:{port}/v1' + variables: + subdomain: + enum: + - development + - staging + - production + port: + default: '8080' +``` + +### `serverVariables` section + +Define the components.serverVariables section in your AsyncAPI document. For each variable used in the server URLs, provide a default value and an optional description. This helps you avoid repeating variable defination. For example, + +```yaml +components: + serverVariables: + subdomain: + enum: + - development + - staging + - production + default: development + port: + default: '8080' +``` + +### Define domain and port variables + +You can use components.serverVariables to avoid repeating variable definations such as domains and ports. To change the values of these variables, update their default values in the components.serverVariables section. Both servers' URLs will reflect the changes. + +Here's the complete AsyncAPI document with the server URL variables: + +```yaml +info: + title: Example API + version: '1.0.0' +servers: + production: + host: '{subdomain}.example.com:{port}' + pathname: /v1 + protocol: amqp + variables: + subdomain: + $ref: '#/components/serverVariables/subdomain' + port: + $ref: '#/components/serverVariables/port' + development: + host: '{subdomain}.example.com:{port}' + pathname: /v1 + protocol: amqp + variables: + subdomain: + $ref: '#/components/serverVariables/subdomain' + port: + $ref: '#/components/serverVariables/port' +components: + serverVariables: + subdomain: + enum: + - development + - staging + - production + default: development + port: + default: '8080' +``` \ No newline at end of file From d585b5c664269233acf0736cc6923e3697dd9cff Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Tue, 12 Dec 2023 16:23:36 +0100 Subject: [PATCH 2/3] Update variable-url.md --- .../asyncapi-document/variable-url.md | 85 +++++++++++++------ 1 file changed, 58 insertions(+), 27 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/variable-url.md b/pages/docs/concepts/asyncapi-document/variable-url.md index 11ccbb6afa5..3f707817c05 100644 --- a/pages/docs/concepts/asyncapi-document/variable-url.md +++ b/pages/docs/concepts/asyncapi-document/variable-url.md @@ -1,41 +1,49 @@ --- -title: Variable URL +title: Server Variables weight: 275 --- -Servers benefit from a defined base URL and rules for URL variables. You can easily manage multiple endpoints, handling various server configurations and environments. +Server's URL consists of `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. This way you can easily manage multiple endpoints, handling various server configurations and environments. -URL variables are placeholders for values you can replace during runtime. AsyncAPI enables you to construct dynamic URLs while enhancing the flexibility and maintainability of your AsyncAPI documents. +## Add variables -## Add dynamic variables +You can add variables to `server.host` and `server.pathname` and you do it by adding a variable in between curly braces like `{braces}`. Next, you use `server.variables` to provide definitions of your variables. Leverage `components.serverVariables` to enable reusable variable definitions across multiple servers. -Use the `server.url` and `server.variables` to add variables to a server URL. Leverage `components.serverVariables` to enable reusable variable definitions across multiple servers. - -The diagram below describes how to use variable urls in AsyncAPI. +The diagram below describes how to use reusable variables in AsyncAPI. ```mermaid -graph TD - - A[AsyncAPI Server] - B[Components] - C[Server URL] - -style A fill:#47BCEE,stroke:#47BCEE; -style B fill:#47BCEE,stroke:#47BCEE; -style C fill:#47BCEE,stroke:#47BCEE; - - B -->|Defines serverVariables| C - C -->|Reusable variables| A +graph LR + C[servers] + F[host] + I[protocol] + E[pathname] + A[components] + B[serverVariables] + D[variables] + C --> F + C --> I + C --> E + C --> D + D --> |$ref| B + A --> B + + style C fill:#47BCEE,stroke:#000; + style D fill:#47BCEE,stroke:#000; + style F fill:#47BCEE,stroke:#000; + style E fill:#47BCEE,stroke:#000 ``` +You put variables in `host` and/or `pathname`. Next, you define reusable variables in `components.serverVariables`. Last, you make sure that `server.variables` from your server reference definitions from `components.serverVariables` using `$ref`. + ### Servers section -Define the servers section in your AsyncAPI document, and include the base URLs for your API servers. Use placeholders enclosed in curly braces {} to represent the variables in the server URL. For example: +Define the servers section in your AsyncAPI document, and include the `host` and `pathname` for your API servers. Use placeholders enclosed in curly braces {} to represent the variables in the server. For example: ```yaml servers: production: - url: 'https://{subdomain}.example.com:{port}/v1' + host: '{subdomain}.example.com:{port}' + pathname: '/{version} variables: subdomain: enum: @@ -44,11 +52,15 @@ servers: - production port: default: '8080' + version: + enum: + - v1 + - v2 ``` ### `serverVariables` section -Define the components.serverVariables section in your AsyncAPI document. For each variable used in the server URLs, provide a default value and an optional description. This helps you avoid repeating variable defination. For example, +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. This helps you avoid repeating variable defination. For example: ```yaml components: @@ -61,30 +73,43 @@ components: default: development port: default: '8080' + version: + enum: + - v1 + - v2 ``` ### Define domain and port variables -You can use components.serverVariables to avoid repeating variable definations such as domains and ports. To change the values of these variables, update their default values in the components.serverVariables section. Both servers' URLs will reflect the changes. +Use `components.serverVariables` in your server using [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) to avoid repeating the information: -Here's the complete AsyncAPI document with the server URL variables: +```yml + variables: + subdomain: + $ref: '#/components/serverVariables/subdomain' +``` + +Here's the complete AsyncAPI document with the servers' variables for the `host` field: ```yaml +asyncapi: 3.0.0 info: title: Example API version: '1.0.0' servers: production: host: '{subdomain}.example.com:{port}' - pathname: /v1 + pathname: '/{version}' protocol: amqp variables: subdomain: $ref: '#/components/serverVariables/subdomain' port: $ref: '#/components/serverVariables/port' + version: + $ref: '#/components/serverVariables/version' development: - host: '{subdomain}.example.com:{port}' + host: '{subdomain}.dev.example.com:{port}' pathname: /v1 protocol: amqp variables: @@ -92,6 +117,8 @@ servers: $ref: '#/components/serverVariables/subdomain' port: $ref: '#/components/serverVariables/port' + version: + $ref: '#/components/serverVariables/version' components: serverVariables: subdomain: @@ -102,4 +129,8 @@ components: default: development port: default: '8080' -``` \ No newline at end of file + version: + enum: + - v1 + - v2 +``` From cba46e0da8a43f430856e48283f72402a7499a46 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Tue, 12 Dec 2023 08:51:40 -0800 Subject: [PATCH 3/3] tw editorial fixes --- .../concepts/asyncapi-document/variable-url.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/variable-url.md b/pages/docs/concepts/asyncapi-document/variable-url.md index 3f707817c05..8c7c9341527 100644 --- a/pages/docs/concepts/asyncapi-document/variable-url.md +++ b/pages/docs/concepts/asyncapi-document/variable-url.md @@ -1,13 +1,13 @@ --- -title: Server Variables +title: Server variables weight: 275 --- -Server's URL consists of `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. This way you can easily manage multiple endpoints, handling various server configurations and environments. +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` and you do it by adding a variable in between curly braces like `{braces}`. Next, you use `server.variables` to provide definitions of your variables. Leverage `components.serverVariables` to enable reusable variable definitions across multiple servers. +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. @@ -33,11 +33,11 @@ graph LR style E fill:#47BCEE,stroke:#000 ``` -You put variables in `host` and/or `pathname`. Next, you define reusable variables in `components.serverVariables`. Last, you make sure that `server.variables` from your server reference definitions from `components.serverVariables` using `$ref`. +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, and include the `host` and `pathname` for your API servers. Use placeholders enclosed in curly braces {} to represent the variables in the server. For example: +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: ```yaml servers: @@ -60,7 +60,7 @@ servers: ### `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. This helps you avoid repeating variable defination. For example: +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: ```yaml components: @@ -81,7 +81,7 @@ components: ### Define domain and port variables -Use `components.serverVariables` in your server using [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) to avoid repeating the information: +Use `components.serverVariables` in your server using the [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) to avoid repeating information: ```yml variables: