Merge pull request asyncapi#170 from asyncapi/feature/protocol-objects

fmvilas · web-flow · commit a9b2e2bef265 · 2019-03-13T20:31:15.000+01:00
Add support for Protocol Info objects
diff --git a/examples/next/rpc-client.yml b/examples/next/rpc-client.yml
@@ -0,0 +1,70 @@
+asyncapi: '2.0.0'
+id: 'urn:rpc:example:client'
+defaultContentType: application/json
+
+info:
+  title: RPC Client Example
+  description: This example demonstrates how to define an RPC client.
+  version: '1.0.0'
+
+servers:
+  - url: rabbitmq.example.org
+    scheme: amqp
+
+channels:
+  '{queue}':
+    parameters:
+      - name: queue
+        schema:
+          type: string
+          pattern: '^amq\\.gen\\-.+$'
+    protocolInfo:
+      amqp-0-9-1:
+        channelIsQueue: true
+        queue:
+          randomName: true
+          exclusive: true
+    subscribe:
+      operationId: receiveSumResult
+      protocolInfo:
+        amqp-0-9-1:
+          noAck: true
+      message:
+        correlationId:
+          location: $message.header#/correlation_id
+        payload:
+          type: object
+          properties:
+            result:
+              type: number
+              examples:
+                - 7
+
+  rpc_queue:
+    protocolInfo:
+      amqp-0-9-1:
+        channelIsQueue: true
+        queue:
+          durable: false
+    publish:
+      operationId: requestSum
+      protocolInfo:
+        amqp-0-9-1:
+          ack: true
+      message:
+        protocolInfo:
+          amqp-0-9-1:
+            properties:
+              reply_to:
+                type: string
+        correlationId:
+          location: $message.header#/correlation_id
+        payload:
+          type: object
+          properties:
+            numbers:
+              type: array
+              items:
+                type: number
+              examples:
+                - [4,3]
diff --git a/examples/next/rpc-server.yml b/examples/next/rpc-server.yml
@@ -0,0 +1,67 @@
+asyncapi: '2.0.0'
+id: 'urn:rpc:example:server'
+defaultContentType: application/json
+
+info:
+  title: RPC Server Example
+  description: This example demonstrates how to define an RPC server.
+  version: '1.0.0'
+
+servers:
+  - url: rabbitmq.example.org
+    scheme: amqp
+
+channels:
+  '{queue}':
+    parameters:
+      - name: queue
+        schema:
+          type: string
+          pattern: '^amq\\.gen\\-.+$'
+    protocolInfo:
+      amqp-0-9-1:
+        channelIsQueue: true
+        queue:
+          randomName: true
+          exclusive: true
+    publish:
+      operationId: sendSumResult
+      protocolInfo:
+        amqp-0-9-1:
+          ack: true
+      message:
+        correlationId:
+          location: $message.header#/correlation_id
+        payload:
+          type: object
+          properties:
+            result:
+              type: number
+              examples:
+                - 7
+
+  rpc_queue:
+    protocolInfo:
+      amqp-0-9-1:
+        channelIsQueue: true
+        queue:
+          durable: false
+    subscribe:
+      operationId: sum
+      message:
+        protocolInfo:
+          amqp-0-9-1:
+            properties:
+              reply_to:
+                type: string
+        correlationId:
+          location: $message.header#/correlation_id
+        payload:
+          type: object
+          properties:
+            numbers:
+              type: array
+              items:
+                type: number
+              examples:
+                - [4,3]
diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md
@@ -61,6 +61,7 @@ Means that the [application](#definitionsApplication) is a [consumer](#definitio
       - [XML Object](#xmlObject)
       - [Security Scheme Object](#securitySchemeObject)
       - [Parameter Object](#parameterObject)
+      - [Protocol Info Object](#protocolInfoObject)
       - [Correlation ID Object](#correlationIdObject)
       - [Specification Extensions](#specificationExtensions)
 
@@ -516,6 +517,7 @@ Field Name | Type | Description
 <a name="channelItemObjectSubscribe"></a>subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation.
 <a name="channelItemObjectPublish"></a>publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation.
 <a name="channelItemObjectParameters"></a>parameters | [[Parameter Object](#parameterObject) &#124; [Reference Object](#referenceObject)] | A list of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)).
+<a name="channelItemObjectProtocolInfo"></a>protocolInfo | Map[`string`, [Protocol Info Object](#protocolInfoObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.
 
 This object can be extended with [Specification Extensions](#specificationExtensions).
 
@@ -539,6 +541,12 @@ This object can be extended with [Specification Extensions](#specificationExtens
         }
       }
     }
+  },
+  "amqp-0-9-1": {
+    "channelIsQueue": true,
+    "queue": {
+      "exclusive": true
+    }
   }
 }
 ```
@@ -554,7 +562,10 @@ subscribe:
         user:
           $ref: "#/components/schemas/user"
         signup:
-          $ref: "#/components/schemas/signup"
+amqp-0-9-1:
+  channelIsQueue: true
+  queue:
+    exclusive: true
 ```
 
 Using `oneOf` to specify multiple messages per operation:
@@ -599,6 +610,7 @@ Field Name | Type | Description
 <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="operationObjectTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of operations.
 <a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
+<a name="operationObjectProtocolInfo"></a>protocolInfo | Map[`string`, [Protocol Info Object](#protocolInfoObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
 <a name="operationObjectMessage"></a>message | [Message Object](#messageObject) | A definition of the message that will be published or received on this channel. `oneOf` is allowed here to specify multiple messages, however, **a message MUST be valid only against one of the referenced message objects.**
 
 This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -633,6 +645,9 @@ This object can be extended with [Specification Extensions](#specificationExtens
         }
       }
     }
+  },
+  "amqp-0-9-1": {
+    "noAck": true
   }
 }
 ```
@@ -657,6 +672,8 @@ message:
         $ref: "#/components/schemas/userCreate"
       signup:
         $ref: "#/components/schemas/signup"
+amqp-0-9-1:
+  noAck: true
 ```
 
 
@@ -713,6 +730,42 @@ user.{userId}.signup:
 
 
 
+#### <a name="protocolInfoObject"></a>Protocol Info Object
+
+Free-form key-value object describing protocol-specific definitions for channels, operations, and messages.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+<a name="protocolInfoObjectProtocolName"></a>{protocol} | `Map` | Protocol-specific information. This map is free-form and MUST not be validated by parsers.
+
+##### Protocol Info Object Example
+
+```json
+{
+  "amqp-0-9-1": {
+    "channelIsQueue": true,
+    "queue": {
+      "randomName": true,
+      "exclusive": true
+    }
+  }
+}
+```
+
+```yaml
+amqp-0-9-1:
+  channelIsQueue: true
+  queue:
+    randomName: true
+    exclusive: true
+```
+
+
+
+
+
 #### <a name="streamObject"></a>Stream Object
 
 Holds the framing configuration and the read/write operations for the streaming API.
@@ -817,6 +870,7 @@ Field Name | Type | Description
 <a name="messageObjectDescription"></a>description | `string` | A verbose explanation of the message. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="messageObjectTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of messages.
 <a name="messageObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message.
+<a name="messageObjectProtocolInfo"></a>protocolInfo | Map[`string`, [Protocol Info Object](#protocolInfoObject)] | A free-form 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 | [Map[`string`, `any`]] | An array with examples of valid message objects.
 
 This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -859,6 +913,11 @@ This object can be extended with [Specification Extensions](#specificationExtens
   "correlationId": {
     "description": "Default Correlation ID",
     "location": "$message.header#/correlationId"
+  },
+  "amqp-0-9-1": {
+    "properties": {
+      "delivery_mode": 2
+    }
   }
 }
 ```
@@ -890,6 +949,9 @@ payload:
 correlationId:
   description: Default Correlation ID
   location: $message.header#/correlationId
+amqp-0-9-1:
+  properties:
+    delivery_mode: 2
 ```
 
 Example using Google's protobuf to define the payload:
diff --git a/versions/next/schema.json b/versions/next/schema.json
