From f8d26f867c3f8d885dd810b84bd21795505893d7 Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Thu, 21 Apr 2022 13:53:12 +0200 Subject: [PATCH 01/16] chore: update release branch to 3.0 (#753) --- examples/social-media/backend/asyncapi.yaml | 2 +- examples/social-media/comments-service/asyncapi.yaml | 2 +- examples/social-media/frontend/asyncapi.yaml | 2 +- examples/social-media/notification-service/asyncapi.yaml | 2 +- examples/social-media/public-api/asyncapi.yaml | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/examples/social-media/backend/asyncapi.yaml b/examples/social-media/backend/asyncapi.yaml index 5f7cb94e..a25f9321 100644 --- a/examples/social-media/backend/asyncapi.yaml +++ b/examples/social-media/backend/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 2.2.0 +asyncapi: 3.0.0 info: title: Website Backend diff --git a/examples/social-media/comments-service/asyncapi.yaml b/examples/social-media/comments-service/asyncapi.yaml index ce8f93a9..f7450edd 100644 --- a/examples/social-media/comments-service/asyncapi.yaml +++ b/examples/social-media/comments-service/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 2.2.0 +asyncapi: 3.0.0 info: title: Comments Service diff --git a/examples/social-media/frontend/asyncapi.yaml b/examples/social-media/frontend/asyncapi.yaml index 2837fb6f..15d4fcd7 100644 --- a/examples/social-media/frontend/asyncapi.yaml +++ b/examples/social-media/frontend/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 2.2.0 +asyncapi: 3.0.0 info: title: Website WebSocket Client diff --git a/examples/social-media/notification-service/asyncapi.yaml b/examples/social-media/notification-service/asyncapi.yaml index be78362c..8a67e4ac 100644 --- a/examples/social-media/notification-service/asyncapi.yaml +++ b/examples/social-media/notification-service/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 2.2.0 +asyncapi: 3.0.0 info: title: Notifications Service diff --git a/examples/social-media/public-api/asyncapi.yaml b/examples/social-media/public-api/asyncapi.yaml index 0a7cdde7..5c41dbd9 100644 --- a/examples/social-media/public-api/asyncapi.yaml +++ b/examples/social-media/public-api/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 2.2.0 +asyncapi: 3.0.0 info: title: Public API From 654650097857d5dc7ffbaf876f2180900613f68b Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 12 May 2022 15:21:54 +0200 Subject: [PATCH 02/16] chore: add metadata object --- spec/asyncapi.md | 180 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 141 insertions(+), 39 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 418b2b82..da03d1d4 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -71,6 +71,7 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Tags Object](#tagsObject) - [Tag Object](#tag-object) - [External Documentation Object](#externalDocumentationObject) + - [Metadata Object](#metadataObject) - [Components Object](#componentsObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) @@ -355,21 +356,41 @@ Field Pattern | Type | Description ```json { - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" + "url": "development.gigantic-server.com", + "protocol": "kafka", + "protocolVersion": "1.0.0", + "metadata": { + "name": "DevelopmentServer", + "title": "Development server", + "summary": "A development server", + "description": "A longer description", + "tags": [ + { + "name": "development" + } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://kafka.apache.org/" + } } } ``` ```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' +url: development.gigantic-server.com +protocol: kafka +protocolVersion: 1.0.0 +metadata: + name: DevelopmentServer + title: Development server + summary: A development server + description: A longer description + tags: + - name: development + externalDocs: + description: Find more info here + url: https://kafka.apache.org/ ``` @@ -399,17 +420,40 @@ 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", + "metadata": { + "name": "DevelopmentServer", + "title": "Development server", + "summary": "A development server", + "description": "A longer description", + "tags": [ + { + "name": "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 +metadata: + name: DevelopmentServer + title: Development server + summary: A development server + description: A longer description + tags: + - name: 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): @@ -419,7 +463,6 @@ 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", "tags": [ @@ -431,7 +474,6 @@ 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", "tags": [ @@ -443,7 +485,6 @@ 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", "tags": [ @@ -461,7 +502,6 @@ 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 tags: @@ -469,7 +509,6 @@ servers: 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 tags: @@ -477,7 +516,6 @@ servers: 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 tags: @@ -492,8 +530,10 @@ 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", + "metadata": { + "description": "The production API server", + }, "variables": { "username": { "default": "demo", @@ -519,8 +559,9 @@ 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 + metadata: + description: The production API server variables: username: # note! no enum here means it is an open value @@ -1514,6 +1555,64 @@ description: Find more info here url: https://example.com ``` + +#### Metadata Object + +The object provides metadata about the described object. May contain previously non defined fields. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +name | `string` | A machine-friendly name for the described item. +title | `string` | A human-friendly title for the described item. +summary | `string` | A short summary of what the described item is about. +description | `string` | A verbose explanation of the described item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +tags | Tags Object | A list of tags for API documentation control. Tags can be used for logical grouping of items. +externalDocs | External Documentation Object | Additional external documentation for described item. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +##### Metadata Object Example + +```json +{ + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { + "name": "user", + "description": "User-related messages" + }, + { "name": "signup" }, + { "name": "register" } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + } +} +``` + +```yaml +name: UserSignup +title: User signup +summary: Action to sign a user up. +description: A longer description +tags: +- name: user + description: User-related messages +- name: signup +- name: register +externalDocs: + description: Find more info here + url: https://example.com +``` + + + #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. @@ -1650,16 +1749,18 @@ my.org.User }, "messages": { "userSignUp": { - "summary": "Action to sign a user up.", - "description": "Multiline description of what this action does.\nHere you have another line.\n", - "tags": [ - { - "name": "user" - }, - { - "name": "signup" - } - ], + "metadata": { + "summary": "Action to sign a user up.", + "description": "Multiline description of what this action does.\nHere you have another line.\n", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + } + ] + }, "headers": { "type": "object", "properties": { @@ -1758,13 +1859,14 @@ components: $ref: "#/components/messages/userSignUp" messages: userSignUp: - summary: Action to sign a user up. - description: | - Multiline description of what this action does. - Here you have another line. - tags: - - name: user - - name: signup + metadata: + summary: Action to sign a user up. + description: | + Multiline description of what this action does. + Here you have another line. + tags: + - name: user + - name: signup headers: type: object properties: From fcdbd0dbba5ba53f2366fa0124db198229c23081 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 25 May 2022 11:21:37 +0200 Subject: [PATCH 03/16] fix typos --- spec/asyncapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index da03d1d4..94dac095 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -1558,7 +1558,7 @@ url: https://example.com #### Metadata Object -The object provides metadata about the described object. May contain previously non defined fields. +The object provides metadata about the described object. ##### Fixed Fields @@ -1571,7 +1571,7 @@ Field Name | Type | Description tags | Tags Object | A list of tags for API documentation control. Tags can be used for logical grouping of items. externalDocs | External Documentation Object | Additional external documentation for described item. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object can be extended with [Specification Extensions](#specificationExtensions) and MAY contain previously non defined fields. ##### Metadata Object Example From 4118468f2cd39f44e590a85163f6d543a4c31341 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 26 May 2022 13:11:01 +0200 Subject: [PATCH 04/16] add server and channel traits --- spec/asyncapi.md | 171 +++++++++++++++++++++++++++-------------------- 1 file changed, 100 insertions(+), 71 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 94dac095..774344c6 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -57,7 +57,8 @@ 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 Trait Object](#serverTraitObject) - [Server Variable Object](#serverVariableObject) - [Default Content Type](#defaultContentTypeString) - [Channels Object](#channelsObject) @@ -359,20 +360,18 @@ Field Pattern | Type | Description "url": "development.gigantic-server.com", "protocol": "kafka", "protocolVersion": "1.0.0", - "metadata": { - "name": "DevelopmentServer", - "title": "Development server", - "summary": "A development server", - "description": "A longer description", - "tags": [ - { - "name": "development" - } - ], - "externalDocs": { - "description": "Find more info here", - "url": "https://kafka.apache.org/" + "name": "DevelopmentServer", + "title": "Development server", + "summary": "A development server", + "description": "A longer description", + "tags": [ + { + "name": "development" } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://kafka.apache.org/" } } ``` @@ -381,16 +380,15 @@ Field Pattern | Type | Description url: development.gigantic-server.com protocol: kafka protocolVersion: 1.0.0 -metadata: - name: DevelopmentServer - title: Development server - summary: A development server - description: A longer description - tags: +name: DevelopmentServer +title: Development server +summary: A development server +description: A longer description +tags: - name: development - externalDocs: - description: Find more info here - url: https://kafka.apache.org/ +externalDocs: + description: Find more info here + url: https://kafka.apache.org/ ``` @@ -410,8 +408,9 @@ Field Name | Type | Description 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. +traits | [[Server Trait Object](#serverTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the server object. Traits MUST be merged into the server object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Server Object](#serverObject). -This object MAY be extended with [Specification Extensions](#specificationExtensions). +This object inherits the fields from [Metadata Object](#metadataObject) and MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example @@ -422,20 +421,18 @@ A single server would be described as: "url": "development.gigantic-server.com", "protocol": "kafka", "protocolVersion": "1.0.0", - "metadata": { - "name": "DevelopmentServer", - "title": "Development server", - "summary": "A development server", - "description": "A longer description", - "tags": [ - { - "name": "development" - } - ], - "externalDocs": { - "description": "Find more info here", - "url": "https://kafka.apache.org/" + "name": "DevelopmentServer", + "title": "Development server", + "summary": "A development server", + "description": "A longer description", + "tags": [ + { + "name": "development" } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://kafka.apache.org/" } } ``` @@ -444,16 +441,15 @@ A single server would be described as: url: development.gigantic-server.com protocol: kafka protocolVersion: 1.0.0 -metadata: - name: DevelopmentServer - title: Development server - summary: A development server - description: A longer description - tags: +name: DevelopmentServer +title: Development server +summary: A development server +description: A longer description +tags: - name: development - externalDocs: - description: Find more info here - url: https://kafka.apache.org/ +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): @@ -531,9 +527,7 @@ The following shows how variables can be used for a server configuration: "production": { "url": "{username}.gigantic-server.com:{port}/{basePath}", "protocol": "secure-mqtt", - "metadata": { - "description": "The production API server", - }, + "description": "The production API server", "variables": { "username": { "default": "demo", @@ -560,8 +554,7 @@ servers: production: url: '{username}.gigantic-server.com:{port}/{basePath}' protocol: secure-mqtt - metadata: - description: The production API server + description: The production API server variables: username: # note! no enum here means it is an open value @@ -578,6 +571,41 @@ servers: ``` + +#### Server Trait Object + +Describes a trait that MAY be applied to an [Server Object](#serverObject). This object MAY contain any property from the [Server Object](#serverObject), except `url`, `protocol`, `protocolVersion`, `variables` and `traits`. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +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. +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 inherits the fields from [Metadata Object](#metadataObject) and MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Server Trait Object Example + +```json +{ + "security": { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } +} +``` + +```yaml +security: + petstore_auth: + - "write:pets" + - "read:pets" +``` + + #### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -850,7 +878,9 @@ onUserSignUp: ``` +#### Channel Trait Object +Describes a trait that MAY be applied to an [Channel Object](#channelObject). This object MAY contain any property from the [Channel Object](#channelObject), except `parameters` and `traits`. #### Operation Object @@ -1660,6 +1690,8 @@ Field Name | Type | Description correlationIds | Map[`string`, [Correlation ID Object](#correlationIdObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlationIdObject). externalDocs | Map[`string`, [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [External Documentation Objects](#externalDocumentationObject). tags | Map[`string`, [Tag Object](#tagObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Tag Objects](#tagObject). + serverTraits | Map[`string`, [Server Trait Object](#serverTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Trait Objects](#serverTraitObject). + channelTraits | Map[`string`, [Channel Trait Object](#channelTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Trait Objects](#channelTraitObject). operationTraits | Map[`string`, [Operation Trait Object](#operationTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Trait Objects](#operationTraitObject). messageTraits | Map[`string`, [Message Trait Object](#messageTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Trait Objects](#messageTraitObject). serverBindings | Map[`string`, [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Bindings Objects](#serverBindingsObject). @@ -1749,18 +1781,16 @@ my.org.User }, "messages": { "userSignUp": { - "metadata": { - "summary": "Action to sign a user up.", - "description": "Multiline description of what this action does.\nHere you have another line.\n", - "tags": [ - { - "name": "user" - }, - { - "name": "signup" - } - ] - }, + "summary": "Action to sign a user up.", + "description": "Multiline description of what this action does.\nHere you have another line.\n", + "tags": [ + { + "name": "user" + }, + { + "name": "signup" + } + ], "headers": { "type": "object", "properties": { @@ -1859,14 +1889,13 @@ components: $ref: "#/components/messages/userSignUp" messages: userSignUp: - metadata: - summary: Action to sign a user up. - description: | - Multiline description of what this action does. - Here you have another line. - tags: - - name: user - - name: signup + summary: Action to sign a user up. + description: | + Multiline description of what this action does. + Here you have another line. + tags: + - name: user + - name: signup headers: type: object properties: From 4e2e042e21ab01f753de8088a6f6e24a69d3cd31 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 26 May 2022 13:32:12 +0200 Subject: [PATCH 05/16] fix anchors --- spec/asyncapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 774344c6..5730e785 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -580,8 +580,8 @@ Describes a trait that MAY be applied to an [Server Object](#serverObject). This Field Name | Type | Description ---|:---:|--- -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. -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. +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. +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 inherits the fields from [Metadata Object](#metadataObject) and MAY be extended with [Specification Extensions](#specificationExtensions). From a2db618686a75526a258d525e419bdb98a93acec Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Mon, 3 Oct 2022 12:08:57 +0200 Subject: [PATCH 06/16] fix version of examples --- examples/social-media/backend/asyncapi.yaml | 2 +- examples/social-media/comments-service/asyncapi.yaml | 2 +- examples/social-media/frontend/asyncapi.yaml | 2 +- examples/social-media/notification-service/asyncapi.yaml | 2 +- examples/social-media/public-api/asyncapi.yaml | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/examples/social-media/backend/asyncapi.yaml b/examples/social-media/backend/asyncapi.yaml index a25f9321..5f7cb94e 100644 --- a/examples/social-media/backend/asyncapi.yaml +++ b/examples/social-media/backend/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 3.0.0 +asyncapi: 2.2.0 info: title: Website Backend diff --git a/examples/social-media/comments-service/asyncapi.yaml b/examples/social-media/comments-service/asyncapi.yaml index f7450edd..ce8f93a9 100644 --- a/examples/social-media/comments-service/asyncapi.yaml +++ b/examples/social-media/comments-service/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 3.0.0 +asyncapi: 2.2.0 info: title: Comments Service diff --git a/examples/social-media/frontend/asyncapi.yaml b/examples/social-media/frontend/asyncapi.yaml index 15d4fcd7..2837fb6f 100644 --- a/examples/social-media/frontend/asyncapi.yaml +++ b/examples/social-media/frontend/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 3.0.0 +asyncapi: 2.2.0 info: title: Website WebSocket Client diff --git a/examples/social-media/notification-service/asyncapi.yaml b/examples/social-media/notification-service/asyncapi.yaml index 8a67e4ac..be78362c 100644 --- a/examples/social-media/notification-service/asyncapi.yaml +++ b/examples/social-media/notification-service/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 3.0.0 +asyncapi: 2.2.0 info: title: Notifications Service diff --git a/examples/social-media/public-api/asyncapi.yaml b/examples/social-media/public-api/asyncapi.yaml index 5c41dbd9..0a7cdde7 100644 --- a/examples/social-media/public-api/asyncapi.yaml +++ b/examples/social-media/public-api/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: 3.0.0 +asyncapi: 2.2.0 info: title: Public API From 337682a09242d906be5e63783c58f407d425a536 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Mon, 3 Oct 2022 12:34:26 +0200 Subject: [PATCH 07/16] after rebease --- spec/asyncapi.md | 124 ++++++++--------------------------------------- 1 file changed, 19 insertions(+), 105 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 5730e785..23b5cc64 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -58,9 +58,8 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [License Object](#licenseObject) - [Servers Object](#serversObject) - [Server Object](#serverObject) - - [Server Trait Object](#serverTraitObject) - [Server Variable Object](#serverVariableObject) - - [Default Content Type](#defaultContentTypeString) + - [Default Content Type](#defaultContentTypeString) - [Channels Object](#channelsObject) - [Channel Object](#channelObject) - [Operations Object](#operationsObject) @@ -72,7 +71,6 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Tags Object](#tagsObject) - [Tag Object](#tag-object) - [External Documentation Object](#externalDocumentationObject) - - [Metadata Object](#metadataObject) - [Components Object](#componentsObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) @@ -403,14 +401,15 @@ 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`. protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. +name | `string` | A machine-friendly name for the server. +title | `string` | A human-friendly title for the server. +summary | `string` | A short summary of the server. 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. 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) | Additional external documentation for this server. 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. -traits | [[Server Trait Object](#serverTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the server object. Traits MUST be merged into the server object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Server Object](#serverObject). - -This object inherits the fields from [Metadata Object](#metadataObject) and MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example @@ -571,41 +570,6 @@ servers: ``` - -#### Server Trait Object - -Describes a trait that MAY be applied to an [Server Object](#serverObject). This object MAY contain any property from the [Server Object](#serverObject), except `url`, `protocol`, `protocolVersion`, `variables` and `traits`. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -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. -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 inherits the fields from [Metadata Object](#metadataObject) and MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Trait Object Example - -```json -{ - "security": { - "petstore_auth": [ - "write:pets", - "read:pets" - ] - } -} -``` - -```yaml -security: - petstore_auth: - - "write:pets" - - "read:pets" -``` - - #### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -694,12 +658,19 @@ Field Name | Type | Description ---|:---:|--- 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). 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.** +name | `string` | A machine-friendly name for the server. +title | `string` | A human-friendly title for the server. +summary | `string` | A short summary of the channel. description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. 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. 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). -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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. +<<<<<<< next-major-spec externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. +======= +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this channel. +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. +>>>>>>> after rebease This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -878,10 +849,6 @@ onUserSignUp: ``` -#### Channel Trait Object - -Describes a trait that MAY be applied to an [Channel Object](#channelObject). This object MAY contain any property from the [Channel Object](#channelObject), except `parameters` and `traits`. - #### Operation Object Describes a specific operation. @@ -892,6 +859,8 @@ Field Name | Type | Description ---|:---:|--- 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). 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. +name | `string` | A machine-friendly name for the operation. +title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. 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. @@ -972,8 +941,10 @@ Field Name | Type | Description ---|:---:|--- action | `string` | 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). channel | [Reference Object](#referenceObject) | 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. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +name | `string` | A machine-friendly name for the operation. +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. @@ -1586,63 +1557,6 @@ url: https://example.com ``` -#### Metadata Object - -The object provides metadata about the described object. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | A machine-friendly name for the described item. -title | `string` | A human-friendly title for the described item. -summary | `string` | A short summary of what the described item is about. -description | `string` | A verbose explanation of the described item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | Tags Object | A list of tags for API documentation control. Tags can be used for logical grouping of items. -externalDocs | External Documentation Object | Additional external documentation for described item. - -This object can be extended with [Specification Extensions](#specificationExtensions) and MAY contain previously non defined fields. - -##### Metadata Object Example - -```json -{ - "name": "UserSignup", - "title": "User signup", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { - "name": "user", - "description": "User-related messages" - }, - { "name": "signup" }, - { "name": "register" } - ], - "externalDocs": { - "description": "Find more info here", - "url": "https://example.com" - } -} -``` - -```yaml -name: UserSignup -title: User signup -summary: Action to sign a user up. -description: A longer description -tags: -- name: user - description: User-related messages -- name: signup -- name: register -externalDocs: - description: Find more info here - url: https://example.com -``` - - - #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. From b7b9a6e194b168a5d065a51515c4831a1b8e4bda Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Mon, 3 Oct 2022 12:59:49 +0200 Subject: [PATCH 08/16] update spec --- spec/asyncapi.md | 75 +++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 30 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 23b5cc64..6d1280e7 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -355,38 +355,41 @@ Field Pattern | Type | Description ```json { - "url": "development.gigantic-server.com", - "protocol": "kafka", - "protocolVersion": "1.0.0", - "name": "DevelopmentServer", - "title": "Development server", - "summary": "A development server", - "description": "A longer description", - "tags": [ - { - "name": "development" + "development": { + "url": "development.gigantic-server.com", + "protocol": "kafka", + "protocolVersion": "1.0.0", + "name": "DevelopmentServer", + "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/" } - ], - "externalDocs": { - "description": "Find more info here", - "url": "https://kafka.apache.org/" } } ``` ```yaml -url: development.gigantic-server.com -protocol: kafka -protocolVersion: 1.0.0 -name: DevelopmentServer -title: Development server -summary: A development server -description: A longer description -tags: - - name: development -externalDocs: - description: Find more info here - url: https://kafka.apache.org/ +development: + url: development.gigantic-server.com + protocol: kafka + protocolVersion: 1.0.0 + name: DevelopmentServer + 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/ ``` @@ -426,7 +429,7 @@ A single server would be described as: "description": "A longer description", "tags": [ { - "name": "development" + "name": "env:development" } ], "externalDocs": { @@ -445,7 +448,7 @@ title: Development server summary: A development server description: A longer description tags: - - name: development + - name: "env:development" externalDocs: description: Find more info here url: https://kafka.apache.org/ @@ -460,6 +463,7 @@ The following shows how multiple servers can be described, for example, at the A "url": "development.gigantic-server.com", "protocol": "amqp", "protocolVersion": "0.9.1", + "title": "Development server", "tags": [ { "name": "env:development", @@ -471,6 +475,7 @@ The following shows how multiple servers can be described, for example, at the A "url": "staging.gigantic-server.com", "protocol": "amqp", "protocolVersion": "0.9.1", + "title": "Staging server", "tags": [ { "name": "env:staging", @@ -482,6 +487,7 @@ The following shows how multiple servers can be described, for example, at the A "url": "api.gigantic-server.com", "protocol": "amqp", "protocolVersion": "0.9.1", + "title": "Production server", "tags": [ { "name": "env:production", @@ -499,6 +505,7 @@ servers: 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" @@ -506,6 +513,7 @@ servers: 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" @@ -513,6 +521,7 @@ servers: 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" @@ -526,7 +535,7 @@ The following shows how variables can be used for a server configuration: "production": { "url": "{username}.gigantic-server.com:{port}/{basePath}", "protocol": "secure-mqtt", - "description": "The production API server", + "title": "Production server", "variables": { "username": { "default": "demo", @@ -553,7 +562,7 @@ servers: production: url: '{username}.gigantic-server.com:{port}/{basePath}' protocol: secure-mqtt - description: The production API server + title: Production server variables: username: # note! no enum here means it is an open value @@ -680,6 +689,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": { @@ -719,6 +729,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: @@ -807,6 +818,7 @@ Field Pattern | Type | Description ```json { "onUserSignUp": { + "title": "User sign up", "summary": "Action to sign a user up.", "description": "A longer description", "channel": { @@ -832,6 +844,7 @@ Field Pattern | Type | Description ```yaml onUserSignUp: + title: User sign up summary: Action to sign a user up. description: A longer description channel: @@ -875,6 +888,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": { @@ -906,6 +920,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: From 60113aa23e13c97f5e62725b6992414827afc19e Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Mon, 3 Oct 2022 13:01:58 +0200 Subject: [PATCH 09/16] fix trait object --- spec/asyncapi.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 6d1280e7..25ed03f8 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -956,10 +956,10 @@ Field Name | Type | Description ---|:---:|--- action | `string` | 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). channel | [Reference Object](#referenceObject) | 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. -name | `string` | A machine-friendly name for the operation. -title | `string` | A human-friendly title for the operation. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +name | `string` | A machine-friendly name for the operation. +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. From b87513456a2eff7dce45c49203c355580dccef54 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Mon, 3 Oct 2022 13:15:49 +0200 Subject: [PATCH 10/16] fix security --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 25ed03f8..9e0e68e3 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2378,7 +2378,7 @@ type: userPassword ``` ```yaml -type: apiKey, +type: apiKey in: user ``` From 3c38cdc6fcb4503f8e5535b0a78080d4e376e1d7 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 26 Oct 2022 19:26:54 +0200 Subject: [PATCH 11/16] remove name property --- spec/asyncapi.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 9e0e68e3..9849dbad 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -404,7 +404,6 @@ 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`. protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -name | `string` | A machine-friendly name for the server. title | `string` | A human-friendly title for the server. summary | `string` | A short summary of the server. 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. @@ -667,8 +666,7 @@ Field Name | Type | Description ---|:---:|--- 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). 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.** -name | `string` | A machine-friendly name for the server. -title | `string` | A human-friendly title for the server. +title | `string` | A human-friendly title for the channel. summary | `string` | A short summary of the channel. description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. 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. @@ -872,7 +870,6 @@ Field Name | Type | Description ---|:---:|--- 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). 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. -name | `string` | A machine-friendly name for the operation. title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. @@ -956,7 +953,6 @@ Field Name | Type | Description ---|:---:|--- action | `string` | 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). channel | [Reference Object](#referenceObject) | 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. -name | `string` | A machine-friendly name for the operation. title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. From 4cc425893a1655e6f2f7d5f7bed1dd4f98ae84c4 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 26 Oct 2022 19:31:57 +0200 Subject: [PATCH 12/16] update examples --- spec/asyncapi.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 9849dbad..7c63acbb 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -359,7 +359,6 @@ Field Pattern | Type | Description "url": "development.gigantic-server.com", "protocol": "kafka", "protocolVersion": "1.0.0", - "name": "DevelopmentServer", "title": "Development server", "summary": "A development server", "description": "A longer description", @@ -381,7 +380,6 @@ development: url: development.gigantic-server.com protocol: kafka protocolVersion: 1.0.0 - name: DevelopmentServer title: Development server summary: A development server description: A longer description @@ -422,7 +420,6 @@ A single server would be described as: "url": "development.gigantic-server.com", "protocol": "kafka", "protocolVersion": "1.0.0", - "name": "DevelopmentServer", "title": "Development server", "summary": "A development server", "description": "A longer description", @@ -442,7 +439,6 @@ A single server would be described as: url: development.gigantic-server.com protocol: kafka protocolVersion: 1.0.0 -name: DevelopmentServer title: Development server summary: A development server description: A longer description From eaf75fe809f481a200a64265d9c5e0a57fc28248 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 9 Nov 2022 12:21:03 +0100 Subject: [PATCH 13/16] use https --- spec/asyncapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 7c63acbb..bf05f59b 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -868,7 +868,7 @@ Field Name | Type | Description 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. title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. @@ -951,7 +951,7 @@ Field Name | Type | Description channel | [Reference Object](#referenceObject) | 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. title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. From 0384438b3459f15de98766fb231116fd470ba78b Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 9 Nov 2022 12:22:16 +0100 Subject: [PATCH 14/16] fix conflicts --- spec/asyncapi.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index bf05f59b..3fb94b1d 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -668,12 +668,8 @@ Field Name | Type | Description 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. 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). tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. -<<<<<<< next-major-spec externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. -======= -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this channel. 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. ->>>>>>> after rebease This object MAY be extended with [Specification Extensions](#specificationExtensions). From 4784ff245030a8aada08957dbc045025725cc702 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 9 Nov 2022 12:23:53 +0100 Subject: [PATCH 15/16] fix server external docs --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 3fb94b1d..1b9c1751 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -408,7 +408,7 @@ Field Name | Type | Description 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. 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) | Additional external documentation for this server. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server. 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. ##### Server Object Example From 9cb4551a01323b6dcc54634d55740095bf03d7e6 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Wed, 9 Nov 2022 12:25:46 +0100 Subject: [PATCH 16/16] remove traits --- spec/asyncapi.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 1b9c1751..bfbf16f9 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -1607,8 +1607,6 @@ Field Name | Type | Description correlationIds | Map[`string`, [Correlation ID Object](#correlationIdObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlationIdObject). externalDocs | Map[`string`, [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [External Documentation Objects](#externalDocumentationObject). tags | Map[`string`, [Tag Object](#tagObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Tag Objects](#tagObject). - serverTraits | Map[`string`, [Server Trait Object](#serverTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Trait Objects](#serverTraitObject). - channelTraits | Map[`string`, [Channel Trait Object](#channelTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Trait Objects](#channelTraitObject). operationTraits | Map[`string`, [Operation Trait Object](#operationTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Trait Objects](#operationTraitObject). messageTraits | Map[`string`, [Message Trait Object](#messageTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Trait Objects](#messageTraitObject). serverBindings | Map[`string`, [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Bindings Objects](#serverBindingsObject).