feat: add tags field to Server Object (#809)

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:

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:

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:

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:

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
 

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
 

spec/asyncapi.md

@@ -366,6 +366,7 @@ Field Name | Type | Description
 <a name="serverObjectDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="serverObjectVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value.  The value is used for substitution in the server's URL template.
 <a name="serverObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation.
+<a name="serverObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers.
 <a name="serverObjectBindings"></a>bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -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
 <a name="operationObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
 <a name="operationObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="operationObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.
-<a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.
+<a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations.
 <a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationObjectBindings"></a>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.
 <a name="operationObjectTraits"></a>traits | [[Operation Trait Object](#operationTraitObject) &#124; [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
 <a name="operationTraitObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
 <a name="operationTraitObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
 <a name="operationTraitObjectSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.
-<a name="operationTraitObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.
+<a name="operationTraitObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations.
 <a name="operationTraitObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationTraitObjectBindings"></a>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
 <a name="messageObjectTitle"></a>title | `string` | A human-friendly title for the message.
 <a name="messageObjectSummary"></a>summary | `string` | A short summary of what the message is about.
 <a name="messageObjectDescription"></a>description | `string` | A verbose explanation of the message. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
-<a name="messageObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages.
+<a name="messageObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages.
 <a name="messageObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message.
 <a name="messageObjectBindings"></a>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.
 <a name="messageObjectExamples"></a>examples | [[Message Example Object](#messageExampleObject)] | List of examples.
@@ -1296,7 +1324,7 @@ Field Name | Type | Description
 <a name="messageTraitObjectTitle"></a>title | `string` | A human-friendly title for the message.
 <a name="messageTraitObjectSummary"></a>summary | `string` | A short summary of what the message is about.
 <a name="messageTraitObjectDescription"></a>description | `string` | A verbose explanation of the message. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
-<a name="messageTraitObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages.
+<a name="messageTraitObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages.
 <a name="messageTraitObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message.
 <a name="messageTraitObjectBindings"></a>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.
 <a name="messageTraitObjectExamples"></a>examples | [[Message Example Object](#messageExampleObject)] | List of examples.