Skip to content

Commit

Permalink
feat: add missed "metadata" fields in the Server/Channel/Operation Ob…
Browse files Browse the repository at this point in the history 
…jects (asyncapi#796)

Co-authored-by: Jonas Lagoni <[email protected]>
  • Loading branch information
@magicmatatjahu @jonaslagoni
2 people authored and ue85540 committed Jan 18, 2023
1 parent 1b7a924 commit c8ff048
Showing 1 changed file with 73 additions and 27 deletions.
100 changes: 73 additions & 27 deletions spec/asyncapi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,9 @@ It means that the [application](#definitionsApplication) allows [consumers](#def
- [Contact Object](#contactObject)
- [License Object](#licenseObject)
- [Servers Object](#serversObject)
- [Server Object](#serverObject)
- [Server Object](#serverObject)
- [Server Variable Object](#serverVariableObject)
- [Default Content Type](#defaultContentTypeString)
- [Default Content Type](#defaultContentTypeString)
- [Channels Object](#channelsObject)
- [Channel Object](#channelObject)
- [Operations Object](#operationsObject)
Expand Down Expand Up @@ -357,21 +357,39 @@ Field Pattern | Type | Description

```json
{
"production": {
"development": {
"url": "development.gigantic-server.com",
"description": "Development server",
"protocol": "kafka",
"protocolVersion": "1.0.0"
"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/"
}
}
}
```

```yaml
production:
development:
url: development.gigantic-server.com
description: Development server
protocol: kafka
protocolVersion: '1.0.0'
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/
```


Expand All @@ -386,32 +404,51 @@ 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="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="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="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.
<a name="serverObjectBindings"></a>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
{
"url": "development.gigantic-server.com",
"description": "Development server",
"protocol": "kafka",
"protocolVersion": "1.0.0"
"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/"
}
}
```

```yaml
url: development.gigantic-server.com
description: Development server
protocol: kafka
protocolVersion: '1.0.0'
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):
Expand All @@ -421,9 +458,9 @@ The following shows how multiple servers can be described, for example, at the A
"servers": {
"development": {
"url": "development.gigantic-server.com",
"description": "Development server",
"protocol": "amqp",
"protocolVersion": "0.9.1",
"title": "Development server",
"tags": [
{
"name": "env:development",
Expand All @@ -433,9 +470,9 @@ The following shows how multiple servers can be described, for example, at the A
},
"staging": {
"url": "staging.gigantic-server.com",
"description": "Staging server",
"protocol": "amqp",
"protocolVersion": "0.9.1",
"title": "Staging server",
"tags": [
{
"name": "env:staging",
Expand All @@ -445,9 +482,9 @@ The following shows how multiple servers can be described, for example, at the A
},
"production": {
"url": "api.gigantic-server.com",
"description": "Production server",
"protocol": "amqp",
"protocolVersion": "0.9.1",
"title": "Production server",
"tags": [
{
"name": "env:production",
Expand All @@ -463,25 +500,25 @@ The following shows how multiple servers can be described, for example, at the A
servers:
development:
url: development.gigantic-server.com
description: Development server
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
description: Staging server
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
description: Production server
protocol: amqp
protocolVersion: 0.9.1
title: Production server
tags:
- name: "env:production"
description: "This environment is the live environment available for final users"
Expand All @@ -494,8 +531,8 @@ The following shows how variables can be used for a server configuration:
"servers": {
"production": {
"url": "{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"protocol": "secure-mqtt",
"title": "Production server",
"variables": {
"username": {
"default": "demo",
Expand All @@ -521,8 +558,8 @@ The following shows how variables can be used for a server configuration:
servers:
production:
url: '{username}.gigantic-server.com:{port}/{basePath}'
description: The production API server
protocol: secure-mqtt
title: Production server
variables:
username:
# note! no enum here means it is an open value
Expand Down Expand Up @@ -627,12 +664,14 @@ Field Name | Type | Description
---|:---:|---
<a name="channelObjectAddress"></a>address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions).
<a name="channelObjectMessages"></a>messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.**
<a name="channelObjectTitle"></a>title | `string` | A human-friendly title for the channel.
<a name="channelObjectSummary"></a>summary | `string` | A short summary of the channel.
<a name="channelObjectDescription"></a>description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
<a name="channelObjectServers"></a>servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.
<a name="channelObjectParameters"></a>parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions).
<a name="channelObjectBindings"></a>bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.
<a name="channelObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels.
<a name="channelObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel.
<a name="channelObjectBindings"></a>bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.


This object MAY be extended with [Specification Extensions](#specificationExtensions).
Expand All @@ -642,6 +681,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
```json
{
"address": "users.{userId}",
"title": "Users channel",
"description": "This channel is used to exchange messages about user events.",
"messages": {
"userSignedUp": {
Expand Down Expand Up @@ -681,6 +721,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens

```yaml
address: 'users.{userId}'
title: Users channel
description: This channel is used to exchange messages about user events.
messages:
userSignedUp:
Expand Down Expand Up @@ -769,6 +810,7 @@ Field Pattern | Type | Description
```json
{
"onUserSignUp": {
"title": "User sign up",
"summary": "Action to sign a user up.",
"description": "A longer description",
"channel": {
Expand All @@ -794,6 +836,7 @@ Field Pattern | Type | Description

```yaml
onUserSignUp:
title: User sign up
summary: Action to sign a user up.
description: A longer description
channel:
Expand All @@ -811,8 +854,6 @@ onUserSignUp:
```




#### <a name="operationObject"></a>Operation Object

Describes a specific operation.
Expand All @@ -823,8 +864,9 @@ Field Name | Type | Description
---|:---:|---
<a name="operationObjectAction"></a>action | `string` | **Required**. Allowed values are `send` and `receive`. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel).
<a name="operationObjectChannel"></a>channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.
<a name="operationObjectTitle"></a>title | `string` | A human-friendly title for the operation.
<a name="operationObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
<a name="operationObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
<a name="operationObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
<a name="operationObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.
<a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations.
<a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation.
Expand All @@ -838,6 +880,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens

```json
{
"title": "User sign up",
"summary": "Action to sign a user up.",
"description": "A longer description",
"channel": {
Expand Down Expand Up @@ -874,6 +917,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
```

```yaml
title: User sign up
summary: Action to sign a user up.
description: A longer description
channel:
Expand Down Expand Up @@ -910,6 +954,7 @@ If you're looking to apply traits to a message, see the [Message Trait Object](#

Field Name | Type | Description
---|:---:|---
<a name="operationTraitObjectTitle"></a>title | `string` | A human-friendly title for the operation.
<a name="operationTraitObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
<a name="operationTraitObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
<a name="operationTraitObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.
Expand Down Expand Up @@ -1536,6 +1581,7 @@ description: Find more info here
url: https://example.com
```


#### <a name="referenceObject"></a>Reference Object

A simple object to allow referencing other components in the specification, internally and externally.
Expand Down Expand Up @@ -2341,7 +2387,7 @@ type: userPassword
```

```yaml
type: apiKey,
type: apiKey
in: user
```

Expand Down

0 comments on commit c8ff048

Please sign in to comment.