From 93d22065fbc87cb0d05bd614701a7a73dfb3966f Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 17 Dec 2022 10:12:54 +0100 Subject: [PATCH 01/10] fix: server url bug --- spec/asyncapi.md | 147 ++++++++++++++++++++--------------------------- 1 file changed, 63 insertions(+), 84 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index bc4a0d01f..6cf623e6d 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -356,7 +356,7 @@ Field Pattern | Type | Description ```json { "production": { - "url": "development.gigantic-server.com", + "host": "development.gigantic-server.com", "description": "Development server", "protocol": "kafka", "protocolVersion": "1.0.0" @@ -381,11 +381,11 @@ An object representing a message broker, a server or any other kind of computer Field Name | Type | Description ---|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`, `googlepubsub`. +host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +protocol | `string` | **REQUIRED**. The protocol this server supports for connection. protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's URL template. +description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` template. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. @@ -398,18 +398,18 @@ A single server would be described as: ```json { - "url": "development.gigantic-server.com", - "description": "Development server", + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", "protocol": "kafka", - "protocolVersion": "1.0.0" + "protocolVersion": "9" } ``` ```yaml -url: development.gigantic-server.com -description: Development server +host: kafka.in.mycompany.com:9092 +description: Production Kafka broker. protocol: kafka -protocolVersion: '1.0.0' +protocolVersion: '9' ``` The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): @@ -418,38 +418,38 @@ The following shows how multiple servers can be described, for example, at the A { "servers": { "development": { - "url": "development.gigantic-server.com", - "description": "Development server", + "host": "localhost:5672", + "description": "Development AMQP broker.", "protocol": "amqp", - "protocolVersion": "0.9.1", + "protocolVersion": "0-9-1", "tags": [ { "name": "env:development", - "description": "This environment is meant for developers to run their own tests" + "description": "This environment is meant for developers to run their own tests." } ] }, "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", "protocol": "amqp", - "protocolVersion": "0.9.1", + "protocolVersion": "0-9-1", "tags": [ { "name": "env:staging", - "description": "This environment is a replica of the production environment" + "description": "This environment is a replica of the production environment." } ] }, "production": { - "url": "api.gigantic-server.com", - "description": "Production server", + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", "protocol": "amqp", - "protocolVersion": "0.9.1", + "protocolVersion": "0-9-1", "tags": [ { "name": "env:production", - "description": "This environment is the live environment available for final users" + "description": "This environment is the live environment available for final users." } ] } @@ -460,54 +460,60 @@ The following shows how multiple servers can be described, for example, at the A ```yaml servers: development: - url: development.gigantic-server.com - description: Development server + host: localhost:5672 + description: Development AMQP broker. protocol: amqp - protocolVersion: 0.9.1 + protocolVersion: 0-9-1 tags: - name: "env:development" - description: "This environment is meant for developers to run their own tests" + description: "This environment is meant for developers to run their own tests." staging: - url: staging.gigantic-server.com - description: Staging server + host: rabbitmq-staging.in.mycompany.com:5672 + description: RabbitMQ broker for the staging environment. protocol: amqp - protocolVersion: 0.9.1 + protocolVersion: 0-9-1 tags: - name: "env:staging" - description: "This environment is a replica of the production environment" + description: "This environment is a replica of the production environment." production: - url: api.gigantic-server.com - description: Production server + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. protocol: amqp - protocolVersion: 0.9.1 + protocolVersion: 0-9-1 tags: - name: "env:production" - description: "This environment is the live environment available for final users" + description: "This environment is the live environment available for final users." ``` -The following shows how variables can be used for a server configuration: +#### Server Variable Object + +An object representing a Server Variable for server URL template substitution. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. +default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. +description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +examples | [`string`] | An array of examples of the server variable. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Server Variable Object Example ```json { "servers": { "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", + "host": "{org}.mycompany.com", + "path": "/api/v1", + "description": "The production API server.", + "protocol": "https", "variables": { - "username": { + "org": { "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" + "description": "This value is assigned by the service provider, in this example `mycompany.com`." } } } @@ -518,44 +524,17 @@ The following shows how variables can be used for a server configuration: ```yaml servers: production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt + host: '{org}.mycompany.com' + path: '/api/v1' + description: The production API server. + protocol: https variables: - username: - # note! no enum here means it is an open value + org: default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 + description: This value is assigned by the service provider, in this example `mycompany.com`. ``` -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -examples | [`string`] | An array of examples of the server variable. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - - - - - #### Default Content Type A string representing the default content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). This value MUST be used by schema parsers when the [contentType](#messageObjectContentType) property is omitted. From 95ef6e4ccd6505b545c748199dcd4acdeb99cd67 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 17 Dec 2022 11:48:27 +0100 Subject: [PATCH 02/10] move multi-server example to servers object --- spec/asyncapi.md | 101 +++++++++++++++++++---------------------------- 1 file changed, 40 insertions(+), 61 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 6cf623e6d..f050df734 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -353,67 +353,6 @@ Field Pattern | Type | Description ##### Servers Object Example -```json -{ - "production": { - "host": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. -protocol | `string` | **REQUIRED**. The protocol this server supports for connection. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. -bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "host": "kafka.in.mycompany.com:9092", - "description": "Production Kafka broker.", - "protocol": "kafka", - "protocolVersion": "9" -} -``` - -```yaml -host: kafka.in.mycompany.com:9092 -description: Production Kafka broker. -protocol: kafka -protocolVersion: '9' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - ```json { "servers": { @@ -485,6 +424,46 @@ servers: description: "This environment is the live environment available for final users." ``` + +#### Server Object + +An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +protocol | `string` | **REQUIRED**. The protocol this server supports for connection. +protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. +description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` template. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. +bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Server Object Example + +A single server would be described as: + +```json +{ + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", + "protocol": "kafka", + "protocolVersion": "9" +} +``` + +```yaml +host: kafka.in.mycompany.com:9092 +description: Production Kafka broker. +protocol: kafka +protocolVersion: '9' +``` + #### Server Variable Object An object representing a Server Variable for server URL template substitution. From 3ef1cc05c44164a04f863b7f357f232448047061 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Tue, 17 Jan 2023 08:57:53 +0100 Subject: [PATCH 03/10] Add pathname and change examples --- spec/asyncapi.md | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index f050df734..83d038f3f 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -436,6 +436,7 @@ Field Name | Type | Description host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. protocol | `string` | **REQUIRED**. The protocol this server supports for connection. protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. +pathname | `string` | The path to a resource in the host. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` template. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. @@ -464,6 +465,24 @@ protocol: kafka protocolVersion: '9' ``` +An example of a server that has a `pathname`: + +```json +{ + "host": "api.gemini.com", + "pathname": "/v2/marketdata", + "protocol": "wss", + "description": "Market data v2 is a public API that can stream all market and candle data across books. Market data v2 also supports multiple subscriptions in the same data feed." +} +``` + +```yaml + host: api.gemini.com + pathname: /v2/marketdata + protocol: wss + description: Market data v2 is a public API that can stream all market and candle data across books. Market data v2 also supports multiple subscriptions in the same data feed. +``` + #### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -485,14 +504,13 @@ This object MAY be extended with [Specification Extensions](#specificationExtens { "servers": { "production": { - "host": "{org}.mycompany.com", - "path": "/api/v1", - "description": "The production API server.", - "protocol": "https", + "host": "api.gemini.com", + "pathname": "/v1/marketdata/{symbol}", + "protocol": "wss", + "description": "Market data is a public API that streams all the market data on a given symbol.", "variables": { - "org": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `mycompany.com`." + "symbol": { + "description": "Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`." } } } @@ -503,14 +521,13 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml servers: production: - host: '{org}.mycompany.com' - path: '/api/v1' - description: The production API server. - protocol: https + host: 'api.gemini.com' + pathname: '/v1/marketdata/{symbol}' + protocol: wss + description: Market data is a public API that streams all the market data on a given symbol. variables: - org: - default: demo - description: This value is assigned by the service provider, in this example `mycompany.com`. + symbol: + description: Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`. ``` From a71d125222169fa9ab7336f767515f99b6256f06 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Tue, 17 Jan 2023 09:05:15 +0100 Subject: [PATCH 04/10] fix examples in servers object --- spec/asyncapi.md | 121 +++++++++++++++++++++++------------------------ 1 file changed, 59 insertions(+), 62 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 83d038f3f..17d78b716 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -355,73 +355,70 @@ Field Pattern | Type | Description ```json { - "servers": { - "development": { - "host": "localhost:5672", - "description": "Development AMQP broker.", - "protocol": "amqp", - "protocolVersion": "0-9-1", - "tags": [ - { - "name": "env:development", - "description": "This environment is meant for developers to run their own tests." - } - ] - }, - "staging": { - "host": "rabbitmq-staging.in.mycompany.com:5672", - "description": "RabbitMQ broker for the staging environment.", - "protocol": "amqp", - "protocolVersion": "0-9-1", - "tags": [ - { - "name": "env:staging", - "description": "This environment is a replica of the production environment." - } - ] - }, - "production": { - "host": "rabbitmq.in.mycompany.com:5672", - "description": "RabbitMQ broker for the production environment.", - "protocol": "amqp", - "protocolVersion": "0-9-1", - "tags": [ - { - "name": "env:production", - "description": "This environment is the live environment available for final users." - } - ] - } + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, + "production": { + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users." + } + ] } } ``` ```yaml -servers: - development: - host: localhost:5672 - description: Development AMQP broker. - protocol: amqp - protocolVersion: 0-9-1 - tags: - - name: "env:development" - description: "This environment is meant for developers to run their own tests." - staging: - host: rabbitmq-staging.in.mycompany.com:5672 - description: RabbitMQ broker for the staging environment. - protocol: amqp - protocolVersion: 0-9-1 - tags: - - name: "env:staging" - description: "This environment is a replica of the production environment." - production: - host: rabbitmq.in.mycompany.com:5672 - description: RabbitMQ broker for the production environment. - protocol: amqp - protocolVersion: 0-9-1 - tags: - - name: "env:production" - description: "This environment is the live environment available for final users." +development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests." +staging: + host: rabbitmq-staging.in.mycompany.com:5672 + description: RabbitMQ broker for the staging environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:staging" + description: "This environment is a replica of the production environment." +production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." ``` From a8c95348745dbeb5158f241f5b04ce7a1bbb6289 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Tue, 17 Jan 2023 09:13:49 +0100 Subject: [PATCH 05/10] fix messy merge --- spec/asyncapi.md | 38 ++++++++++++++++---------------------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 3cadb9303..3b4ae0330 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -500,34 +500,28 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { - "servers": { - "production": { - "host": "api.gemini.com", - "pathname": "/v1/marketdata/{symbol}", - "protocol": "wss", - "description": "Market data is a public API that streams all the market data on a given symbol.", - "title": "Market Data API v1", - "variables": { - "symbol": { - "description": "Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`." - } - } + "host": "api.gemini.com", + "pathname": "/v1/marketdata/{symbol}", + "protocol": "wss", + "description": "Market data is a public API that streams all the market data on a given symbol.", + "title": "Market Data API v1", + "variables": { + "symbol": { + "description": "Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`." } } } ``` ```yaml -servers: - production: - host: 'api.gemini.com' - pathname: '/v1/marketdata/{symbol}' - protocol: wss - description: Market data is a public API that streams all the market data on a given symbol. - title: Market Data API v1 - variables: - symbol: - description: Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`. +host: 'api.gemini.com' +pathname: '/v1/marketdata/{symbol}' +protocol: wss +description: Market data is a public API that streams all the market data on a given symbol. +title: Market Data API v1 +variables: + symbol: + description: Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`. ``` From 44bef64aab0ead1003911d868a0e86eca96aef51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Wed, 18 Jan 2023 16:18:06 +0100 Subject: [PATCH 06/10] Update spec/asyncapi.md Co-authored-by: Lukasz Gornicki --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 3b4ae0330..c2dfd5732 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -437,7 +437,7 @@ Field Name | Type | Description description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. title | `string` | A human-friendly title for the server. summary | `string` | A short summary of the server. -variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` template. +variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` and `pathname` template. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server. From 2a115ab6f03aebffd0eb7728dc6be9fb36cf8e29 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Mon, 23 Jan 2023 10:39:59 +0100 Subject: [PATCH 07/10] Improve examples --- spec/asyncapi.md | 49 ++++++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index c2dfd5732..545b9be11 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -467,18 +467,18 @@ An example of a server that has a `pathname`: ```json { - "host": "api.gemini.com", - "pathname": "/v2/marketdata", - "protocol": "wss", - "description": "Market data v2 is a public API that can stream all market and candle data across books. Market data v2 also supports multiple subscriptions in the same data feed." + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." } ``` ```yaml -host: api.gemini.com -pathname: /v2/marketdata -protocol: wss -description: Market data v2 is a public API that can stream all market and candle data across books. Market data v2 also supports multiple subscriptions in the same data feed. +host: rabbitmq.in.mycompany.com:5672 +pathname: /production +protocol: amqp +description: Production RabbitMQ broker (uses the `production` vhost). ``` #### Server Variable Object @@ -500,28 +500,33 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { - "host": "api.gemini.com", - "pathname": "/v1/marketdata/{symbol}", - "protocol": "wss", - "description": "Market data is a public API that streams all the market data on a given symbol.", - "title": "Market Data API v1", + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", "variables": { - "symbol": { - "description": "Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`." + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] } } } ``` ```yaml -host: 'api.gemini.com' -pathname: '/v1/marketdata/{symbol}' -protocol: wss -description: Market data is a public API that streams all the market data on a given symbol. -title: Market Data API v1 +host: 'rabbitmq.in.mycompany.com:5672' +pathname: '/{env}' +protocol: amqp +description: RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`. variables: - symbol: - description: Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`. + env: + description: Environment to connect to. It can be either `production` or `staging`. + enum: + - production + - staging ``` From 100d5045a9ed7eb4f6ca52e22766cb4aac21c097 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Tue, 7 Feb 2023 17:11:32 +0100 Subject: [PATCH 08/10] Update spec/asyncapi.md Co-authored-by: Dale Lane --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index e2f363561..8ccbf4875 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -481,7 +481,7 @@ A single server would be described as: "host": "kafka.in.mycompany.com:9092", "description": "Production Kafka broker.", "protocol": "kafka", - "protocolVersion": "9" + "protocolVersion": "3.2" } ``` From e1b829da8bea00e4926edddc00480fdeea01452f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Tue, 7 Feb 2023 17:11:40 +0100 Subject: [PATCH 09/10] Update spec/asyncapi.md Co-authored-by: Dale Lane --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 8ccbf4875..48eed163e 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -489,7 +489,7 @@ A single server would be described as: host: kafka.in.mycompany.com:9092 description: Production Kafka broker. protocol: kafka -protocolVersion: '9' +protocolVersion: '3.1' ``` An example of a server that has a `pathname`: From cd06f18afc49cea27c279240c0eefe7e799eb1d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Tue, 7 Feb 2023 17:20:20 +0100 Subject: [PATCH 10/10] Address review suggestions --- spec/asyncapi.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 48eed163e..b58fa67dc 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -489,7 +489,7 @@ A single server would be described as: host: kafka.in.mycompany.com:9092 description: Production Kafka broker. protocol: kafka -protocolVersion: '3.1' +protocolVersion: '3.2' ``` An example of a server that has a `pathname`: @@ -1625,10 +1625,10 @@ my.org.User }, "servers": { "development": { - "url": "{stage}.gigantic-server.com:{port}", - "description": "Development server", + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", "protocol": "amqp", - "protocolVersion": "0.9.1", + "protocolVersion": "0-9-1", "variables": { "stage": { "$ref": "#/components/serverVariables/stage" @@ -1642,11 +1642,11 @@ my.org.User "serverVariables": { "stage": { "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" + "description": "This value is assigned by the service provider, in this example `mycompany.com`" }, "port": { - "enum": ["8883", "8884"], - "default": "8883" + "enum": ["5671", "5672"], + "default": "5672" } }, "channels": { @@ -1745,10 +1745,10 @@ components: type: string servers: development: - url: "{stage}.gigantic-server.com:{port}" - description: Development server + url: "{stage}.in.mycompany.com:{port}" + description: RabbitMQ broker protocol: amqp - protocolVersion: 0.9.1 + protocolVersion: 0-9-1 variables: stage: $ref: "#/components/serverVariables/stage" @@ -1757,10 +1757,10 @@ components: serverVariables: stage: default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` + description: This value is assigned by the service provider, in this example `mycompany.com` port: - enum: [8883, 8884] - default: 8883 + enum: [5671, 5672] + default: 5672 channels: user/signedup: subscribe: