diff --git a/components/MDX.js b/components/MDX.js index 8b0be84e989..9f6182efb4c 100644 --- a/components/MDX.js +++ b/components/MDX.js @@ -62,12 +62,6 @@ export function getMDXComponents() { td: props => , pre: props => CodeComponent(props.children.props), code: props => , - details: (props) => -
, - summary: (props) => - , - p: (props) => -

, hr: props =>

, CodeBlock, ChapterSuggestions, diff --git a/pages/about/index.md b/pages/about/index.md index 585dfa7b70a..4714e54ac94 100644 --- a/pages/about/index.md +++ b/pages/about/index.md @@ -100,47 +100,11 @@ All the information about the project's economy, the amount of the donations, th ## FAQs -
-What is the goal of the project? - -

To make asynchronous APIs as successful and mature as REST APIs.

- -
- -
-What protocols does it support? - -

AsyncAPI is protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). For more information, refer to the [AsyncAPI specification documentation](https://www.asyncapi.com/docs/reference/specification/latest#serverBindingsObject). -

- -
- -
-Who are the users of AsyncAPI? - -

AsyncAPI users are those who implement and maintain event-driven architecture. For example, people that write backend API using WebSocket, or people that maintain communication between their microservices using Kafka.

- -
- -
-What is the AsyncAPI Community? - -

It’s the core of the initiative. The AsyncAPI community contributes to the development of the tool, it promotes access and distribution of the specification allowing freedom of use, study, copying, modification, and redistribution to anyone who wishes to do so. The cooperation between these people in all areas of software production generates a substantial improvement in the quality of the software, as well as greater dissemination and sustainability over time, and prioritizing the benefit of society over any other.

- -
- -
-Who can use it? - -

Anyone. All projects under AsyncAPI Initiative are part of the Linux Foundation, licensed under the Apache 2.0 license. It’s open to use and contribution.

- -
- -
-Where can I find more information? - - [Official AsyncAPI Documentation](/docs) - - [Presentation by Fran Méndez, explaining the project](https://www.youtube.com/watch?v=UID1nnuFDtM&list=PLbi1gRlP7piitNgvqhIAvGNZM_kvP0r8R) - -
+- **What is the goal of the project?** To make asynchronous APIs as successful and mature as REST APIs. +- **What protocols does it support?** AsyncAPI is protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). For more information, refer to the [AsyncAPI specification documentation](https://www.asyncapi.com/docs/reference/specification/latest#serverBindingsObject). +- **Who are the users of AsyncAPI?** AsyncAPI users are those who implement and maintain event-driven architecture. For example, people that write backend API using WebSocket, or people that maintain communication between their microservices using Kafka. +- **What is the AsyncAPI Community?** It’s the core of the initiative. The AsyncAPI community contributes to the development of the tool, it promotes access and distribution of the specification allowing freedom of use, study, copying, modification, and redistribution to anyone who wishes to do so. The cooperation between these people in all areas of software production generates a substantial improvement in the quality of the software, as well as greater dissemination and sustainability over time, and prioritizing the benefit of society over any other. +- **Who can use it?** Anyone. All projects under AsyncAPI Initiative are part of the Linux Foundation, licensed under the Apache 2.0 license. It’s open to use and contribution. +- **Where can I find more information?** + - [Official AsyncAPI Documentation](/docs) + - [Presentation by Fran Méndez, explaining the project](https://www.youtube.com/watch?v=UID1nnuFDtM&list=PLbi1gRlP7piitNgvqhIAvGNZM_kvP0r8R) 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..8c7c9341527 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/variable-url.md @@ -0,0 +1,136 @@ +--- +title: Server variables +weight: 275 +--- + +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. + +```mermaid +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 +``` + +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: + +```yaml +servers: + production: + host: '{subdomain}.example.com:{port}' + pathname: '/{version} + variables: + subdomain: + enum: + - development + - staging + - 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 `host` or `pathname`, provide a default value and an optional description to avoid repeating the variable definitions. For example: + +```yaml +components: + serverVariables: + subdomain: + enum: + - development + - staging + - production + default: development + port: + default: '8080' + version: + enum: + - v1 + - v2 +``` + +### Define domain and port variables + +Use `components.serverVariables` in your server using the [Reference Object](/docs/reference/specification/v3.0.0#referenceObject) to avoid repeating information: + +```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: '/{version}' + protocol: amqp + variables: + subdomain: + $ref: '#/components/serverVariables/subdomain' + port: + $ref: '#/components/serverVariables/port' + version: + $ref: '#/components/serverVariables/version' + development: + host: '{subdomain}.dev.example.com:{port}' + pathname: /v1 + protocol: amqp + variables: + subdomain: + $ref: '#/components/serverVariables/subdomain' + port: + $ref: '#/components/serverVariables/port' + version: + $ref: '#/components/serverVariables/version' +components: + serverVariables: + subdomain: + enum: + - development + - staging + - production + default: development + port: + default: '8080' + version: + enum: + - v1 + - v2 +```