From 2a7acb2e2503381648c0ff2caa97588f50edb974 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Thu, 13 Oct 2022 19:48:14 +0200 Subject: [PATCH] feat: unify all referencing mechanisms --- spec/asyncapi.md | 279 ++++++++++++++--------------------------------- 1 file changed, 82 insertions(+), 197 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 231570e6a..788a07cf1 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -75,7 +75,6 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Security Scheme Object](#securitySchemeObject) - - [Security Requirement Object](#security-requirement-object) - [OAuth Flows Object](#oauth-flows-object) - [OAuth Flow Object](#oauth-flow-object) - [Server Bindings Object](#serverBindingsObject) @@ -342,7 +341,7 @@ Field Pattern | Type | Description ```json { - "production": { + "development": { "url": "development.gigantic-server.com", "description": "Development server", "protocol": "kafka", @@ -352,7 +351,7 @@ Field Pattern | Type | Description ``` ```yaml -production: +development: url: development.gigantic-server.com description: Development server protocol: kafka @@ -373,7 +372,7 @@ Field Name | Type | Description protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -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. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme 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. @@ -399,128 +398,82 @@ protocol: kafka protocolVersion: '1.0.0' ``` -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): +Using server variables for dynamic URLs: ```json { - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:development", - "description": "This environment is meant for developers to run their own tests" - } - ] + "url": "{username}.gigantic-server.com:{port}/{basePath}", + "description": "The production API server", + "protocol": "secure-mqtt", + "variables": { + "username": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:staging", - "description": "This environment is a replica of the production environment" - } - ] + "port": { + "enum": [ + "8883", + "8884" + ], + "default": "8883" }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:production", - "description": "This environment is the live environment available for final users" - } - ] + "basePath": { + "default": "v2" } } } ``` ```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - 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 - 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 - 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: +url: '{username}.gigantic-server.com:{port}/{basePath}' +description: The production API server +protocol: secure-mqtt +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: + # Note: open meaning. There is the opportunity to use special base paths as assigned by the provider, default is `v2`. + default: v2 +``` + +Using security mechanisms: ```json { - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "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" - } - } + "url": "broker.company.com", + "description": "Production MQTT broker", + "protocol": "secure-mqtt", + "protocolVersion": "5", + "security": [ + { + "type": "userPassword", + "description": "Connect to the MQTT broker using basic authentication." + }, + { + "type": "X509", + "description": "Connect to the MQTT broker using a X509 certificate." } - } + ] } ``` ```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - 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 +url: broker.company.com +description: Production MQTT broker +protocol: secure-mqtt +protocolVersion: '5' +security: + - type: userPassword + description: Connect to the MQTT broker using basic authentication. + - type: X509 + description: Connect to the MQTT broker using a X509 certificate. ``` @@ -810,7 +763,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. 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. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) 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. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -890,7 +843,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. 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. -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. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) 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. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -2278,6 +2231,7 @@ Field Name | Type | Applies To | Description bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2387,12 +2341,15 @@ bearerFormat: JWT "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { + "availableScopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } - } + }, + "scopes": [ + "write:pets" + ] } ``` @@ -2401,9 +2358,11 @@ type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog - scopes: + availableScopes: write:pets: modify pets in your account read:pets: read your pets +scopes: + - 'write:pets' ``` ###### SASL Sample @@ -2442,7 +2401,7 @@ Field Name | Type | Applies To | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of an absolute URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2450,98 +2409,24 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```JSON { - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" } } ``` ```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets ``` -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` -```yaml -petstore_auth: -- write:pets -- read:pets -``` ### Correlation ID Object