Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: replace server url with server host and pathname #888

Merged
merged 13 commits into from
Feb 13, 2023
Merged

feat: replace server url with server host and pathname #888

Changes from 6 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
93d2206
fix: server url bug
fmvilas Dec 17, 2022
95ef6e4
move multi-server example to servers object
fmvilas Dec 17, 2022
3ef1cc0
Add pathname and change examples
fmvilas Jan 17, 2023
a71d125
fix examples in servers object
fmvilas Jan 17, 2023
3c29f6b
Merge branch 'next-major-spec' into fix-url-server-bug
fmvilas Jan 17, 2023
a8c9534
fix messy merge
fmvilas Jan 17, 2023
44bef64
Update spec/asyncapi.md
fmvilas Jan 18, 2023
2a115ab
Improve examples
fmvilas Jan 23, 2023
0d2c235
Merge branch 'next-major-spec' into fix-url-server-bug
fmvilas Jan 23, 2023
100d504
Update spec/asyncapi.md
fmvilas Feb 7, 2023
e1b829d
Update spec/asyncapi.md
fmvilas Feb 7, 2023
cd06f18
Address review suggestions
fmvilas Feb 7, 2023
d4ed532
Merge branch 'next-major-spec' into fix-url-server-bug
fmvilas Feb 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 98 additions & 166 deletions spec/asyncapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,38 +356,69 @@ Field Pattern | Type | Description
```json
{
"development": {
"url": "development.gigantic-server.com",
"protocol": "kafka",
"protocolVersion": "1.0.0",
"title": "Development server",
"summary": "A development server",
"description": "A longer description",
"host": "localhost:5672",
"description": "Development AMQP broker.",
"protocol": "amqp",
"protocolVersion": "0-9-1",
"tags": [
{
"name": "env:development"
{
"name": "env:development",
"description": "This environment is meant for developers to run their own tests."
}
],
"externalDocs": {
"description": "Find more info here",
"url": "https://kafka.apache.org/"
}
]
},
"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
development:
url: development.gigantic-server.com
protocol: kafka
protocolVersion: 1.0.0
title: Development server
summary: A development server
description: A longer description
host: localhost:5672
description: Development AMQP broker.
protocol: amqp
protocolVersion: 0-9-1
tags:
- name: "env:development"
externalDocs:
description: Find more info here
url: https://kafka.apache.org/
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."
```


Expand All @@ -399,13 +430,14 @@ An object representing a message broker, a server or any other kind of computer

Field Name | Type | Description
---|:---:|---
<a name="serverObjectUrl"></a>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`}`.
<a name="serverObjectProtocol"></a>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`.
<a name="serverObjectHost"></a>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`}`.
<a name="serverObjectProtocol"></a>protocol | `string` | **REQUIRED**. The protocol this server supports for connection.
<a name="serverObjectProtocolVersion"></a>protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc.
<a name="serverObjectPathname"></a>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`}`.
<a name="serverObjectDescription"></a>description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="serverObjectTitle"></a>title | `string` | A human-friendly title for the server.
<a name="serverObjectSummary"></a>summary | `string` | A short summary of the server.
<a name="serverObjectDescription"></a>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.
<a name="serverObjectVariables"></a>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.
<a name="serverObjectVariables"></a>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.
<a name="serverObjectSecurity"></a>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.
<a name="serverObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers.
<a name="serverObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server.
Expand All @@ -417,163 +449,38 @@ A single server would be described as:

```json
{
"url": "development.gigantic-server.com",
"host": "kafka.in.mycompany.com:9092",
"description": "Production Kafka broker.",
"protocol": "kafka",
"protocolVersion": "1.0.0",
"title": "Development server",
"summary": "A development server",
"description": "A longer description",
"tags": [
{
"name": "env:development"
}
],
"externalDocs": {
"description": "Find more info here",
"url": "https://kafka.apache.org/"
}
"protocolVersion": "9"
}
```

```yaml
url: development.gigantic-server.com
host: kafka.in.mycompany.com:9092
description: Production Kafka broker.
protocol: kafka
protocolVersion: 1.0.0
title: Development server
summary: A development server
description: A longer description
tags:
- name: "env:development"
externalDocs:
description: Find more info here
url: https://kafka.apache.org/
```

The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers):

```json
{
"servers": {
"development": {
"url": "development.gigantic-server.com",
"protocol": "amqp",
"protocolVersion": "0.9.1",
"title": "Development server",
"tags": [
{
"name": "env:development",
"description": "This environment is meant for developers to run their own tests"
}
]
},
"staging": {
"url": "staging.gigantic-server.com",
"protocol": "amqp",
"protocolVersion": "0.9.1",
"title": "Staging server",
"tags": [
{
"name": "env:staging",
"description": "This environment is a replica of the production environment"
}
]
},
"production": {
"url": "api.gigantic-server.com",
"protocol": "amqp",
"protocolVersion": "0.9.1",
"title": "Production server",
"tags": [
{
"name": "env:production",
"description": "This environment is the live environment available for final users"
}
]
}
}
}
protocolVersion: '9'
```

```yaml
servers:
development:
url: development.gigantic-server.com
protocol: amqp
protocolVersion: 0.9.1
title: Development server
tags:
- name: "env:development"
description: "This environment is meant for developers to run their own tests"
staging:
url: staging.gigantic-server.com
protocol: amqp
protocolVersion: 0.9.1
title: Staging server
tags:
- name: "env:staging"
description: "This environment is a replica of the production environment"
production:
url: api.gigantic-server.com
protocol: amqp
protocolVersion: 0.9.1
title: Production server
tags:
- name: "env:production"
description: "This environment is the live environment available for final users"
```

The following shows how variables can be used for a server configuration:
An example of a server that has a `pathname`:

```json
{
"servers": {
"production": {
"url": "{username}.gigantic-server.com:{port}/{basePath}",
"protocol": "secure-mqtt",
"title": "Production server",
"variables": {
"username": {
"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"
}
}
}
}
"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
servers:
production:
url: '{username}.gigantic-server.com:{port}/{basePath}'
protocol: secure-mqtt
title: Production server
variables:
username:
# note! no enum here means it is an open value
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
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.
```


#### <a name="serverVariableObject"></a>Server Variable Object

An object representing a Server Variable for server URL template substitution.
Expand All @@ -589,8 +496,33 @@ Field Name | Type | Description

This object MAY be extended with [Specification Extensions](#specificationExtensions).

##### Server Variable Object Example

```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",
"variables": {
"symbol": {
"description": "Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`."
}
}
}
```

```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
variables:
symbol:
description: Symbols are formatted as `CCY1CCY2` where prices are in `CCY2` and quantities are in `CCY1`.
```


#### <a name="defaultContentTypeString"></a>Default Content Type
Expand Down