diff --git a/examples/social-media/backend/asyncapi.yaml b/examples/social-media/backend/asyncapi.yaml index cefc2f98..5f7cb94e 100644 --- a/examples/social-media/backend/asyncapi.yaml +++ b/examples/social-media/backend/asyncapi.yaml @@ -13,6 +13,13 @@ servers: bindings: mqtt: clientId: websocketServer + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/social-media/comments-service/asyncapi.yaml b/examples/social-media/comments-service/asyncapi.yaml index 0c0bddfd..ce8f93a9 100644 --- a/examples/social-media/comments-service/asyncapi.yaml +++ b/examples/social-media/comments-service/asyncapi.yaml @@ -12,6 +12,13 @@ servers: bindings: mqtt: clientId: comment-service + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/social-media/notification-service/asyncapi.yaml b/examples/social-media/notification-service/asyncapi.yaml index 9952c962..be78362c 100644 --- a/examples/social-media/notification-service/asyncapi.yaml +++ b/examples/social-media/notification-service/asyncapi.yaml @@ -11,6 +11,13 @@ servers: bindings: mqtt: clientId: notification-service + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/social-media/public-api/asyncapi.yaml b/examples/social-media/public-api/asyncapi.yaml index 9e9ea1ef..0a7cdde7 100644 --- a/examples/social-media/public-api/asyncapi.yaml +++ b/examples/social-media/public-api/asyncapi.yaml @@ -12,6 +12,13 @@ servers: bindings: mqtt: clientId: public-api + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/streetlights-kafka.yml b/examples/streetlights-kafka.yml index 413c36ff..91611115 100644 --- a/examples/streetlights-kafka.yml +++ b/examples/streetlights-kafka.yml @@ -21,12 +21,26 @@ servers: description: Test broker secured with scramSha256 security: - saslScram: [] + tags: + - name: "env:test-scram" + description: "This environment is meant for running internal tests through scramSha256" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:private" + description: "This resource is private and only available to certain users" mtls-connections: url: test.mykafkacluster.org:28092 protocol: kafka-secure description: Test broker secured with X509 security: - certs: [] + tags: + - name: "env:test-mtls" + description: "This environment is meant for running internal tests through mtls" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:private" + description: "This resource is private and only available to certain users" defaultContentType: application/json diff --git a/examples/streetlights-mqtt.yml b/examples/streetlights-mqtt.yml index 450ec442..b3721d87 100644 --- a/examples/streetlights-mqtt.yml +++ b/examples/streetlights-mqtt.yml @@ -33,6 +33,13 @@ servers: - streetlights:off - streetlights:dim - openIdConnectWellKnown: [] + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" defaultContentType: application/json diff --git a/spec/asyncapi.md b/spec/asyncapi.md index fb6db37b..cb470825 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -366,6 +366,7 @@ Field Name | Type | Description 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. 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). @@ -399,19 +400,37 @@ The following shows how multiple servers can be described, for example, at the A "url": "development.gigantic-server.com", "description": "Development server", "protocol": "amqp", - "protocolVersion": "0.9.1" + "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" + "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" + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users" + } + ] } } } @@ -424,16 +443,25 @@ servers: 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: @@ -714,7 +742,7 @@ Field Name | Type | Description 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 API documentation control. Tags can be used for logical grouping of operations. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | 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. traits | [[Operation Trait Object](#operationTraitObject) | [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. @@ -825,7 +853,7 @@ Field Name | Type | Description 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. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | 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. @@ -1097,7 +1125,7 @@ Field Name | Type | Description title | `string` | A human-friendly title for the message. summary | `string` | A short summary of what the message is about. description | `string` | A verbose explanation of the message. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. examples | [[Message Example Object](#messageExampleObject)] | List of examples. @@ -1296,7 +1324,7 @@ Field Name | Type | Description title | `string` | A human-friendly title for the message. summary | `string` | A short summary of what the message is about. description | `string` | A verbose explanation of the message. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. examples | [[Message Example Object](#messageExampleObject)] | List of examples.