From 928f6045067f43d3b330cea249144e00b1cf3f64 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 26 May 2022 13:11:01 +0200 Subject: [PATCH] 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 ad5da1158..72e135f38 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) @@ -346,20 +347,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/" } } ``` @@ -368,16 +367,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/ ``` @@ -397,8 +395,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 @@ -409,20 +408,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/" } } ``` @@ -431,16 +428,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): @@ -518,9 +514,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", @@ -547,8 +541,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 @@ -565,6 +558,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. @@ -837,7 +865,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 @@ -1645,6 +1675,8 @@ Field Name | Type | Description securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). correlationIds | Map[`string`, [Correlation ID Object](#correlationIdObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlationIdObject). + 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). @@ -1734,18 +1766,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": { @@ -1844,14 +1874,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: