From b0c2f9c086d940e8016ec1fa60107fe74cc070db Mon Sep 17 00:00:00 2001
From: Sergio Moya <1083296+smoya@users.noreply.github.com>
Date: Thu, 22 Sep 2022 10:55:34 +0200
Subject: [PATCH] feat: add tags field to Server Object (#809)

---
 examples/social-media/backend/asyncapi.yaml   |  7 ++++
 .../comments-service/asyncapi.yaml            |  7 ++++
 .../notification-service/asyncapi.yaml        |  7 ++++
 .../social-media/public-api/asyncapi.yaml     |  7 ++++
 examples/streetlights-kafka.yml               | 14 +++++++
 examples/streetlights-mqtt.yml                |  7 ++++
 spec/asyncapi.md                              | 42 +++++++++++++++----
 7 files changed, 84 insertions(+), 7 deletions(-)

diff --git a/examples/social-media/backend/asyncapi.yaml b/examples/social-media/backend/asyncapi.yaml
index cefc2f98c..5f7cb94e5 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 0c0bddfd4..ce8f93a9e 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 9952c962d..be78362c9 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 9e9ea1efa..0a7cdde79 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 413c36ff9..916111154 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 450ec442f..b3721d878 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 fb6db37b3..cb470825f 100644
--- a/spec/asyncapi.md
+++ b/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.