chore: add asyncapi.yaml file (#42)

* chore: add asyncapi.yaml file

* simplify

* remove comment

* The noblest pleasure is the joy of understanding - Leonardo Da Vinci

* happiness is making typos

* reference content from https://bit.ly/asyncapi

* copy/paste from tutorial

* Use x-servers extension based on asyncapi/spec#531

asyncapi.yaml

@@ -0,0 +1,115 @@
+asyncapi: '2.0.0' # Go parser does not support 2.1.0 at this moment.
+info:
+  title: AsyncAPI Event-Gateway demo API
+  version: 1.0.0-alpha
+  description: This API lets users interact with an instance of the [AsyncAPI Event-Gateway](https://github.com/asyncapi/event-gateway).
+defaultContentType: application/json
+servers:
+  asyncapi-event-gateway-demo:
+    url: 'event-gateway-demo.asyncapi.org:28002'
+    protocol: kafka
+    description: AsyncAPI [Event-Gateway](https://github.com/asyncapi/event-gateway) demo Kafka proxy. Expected messages are based on a small portion of the [StreetLights tutorial](https://bit.ly/asyncapi).
+  asyncapi-event-gateway-demo-validation:
+    url: 'event-gateway-demo.asyncapi.org:5000/ws'
+    protocol: ws
+    description: AsyncAPI [Event-Gateway](https://github.com/asyncapi/event-gateway) demo. Subscribe for Kafka proxy message validation errors.
+  asyncapi-kafka-test:
+    url: 'asyncapi-kafka-test-asyncapi-8f90.aivencloud.com:20472' # Kafka with 3 brokers.
+    protocol: kafka-secure
+    description: AsyncAPI Kafka test broker. Private.
+    x-eventgateway-dial-mapping: '0.0.0.0:20473,event-gateway-demo.asyncapi.org:20473|0.0.0.0:20474,event-gateway-demo.asyncapi.org:20474|0.0.0.0:20475,event-gateway-demo.asyncapi.org:20475' # Dynamic ports starts at 20473
+channels:
+  event-gateway-demo:
+    description: Demo Kafka topic for asyncapi-event-gateway-demo server. Users can send their events to this topic and see how message validation happens on the fly based on this right AsyncAPI file by connecting to `event-gateway-demo-validation-events` channel (`asyncapi-event-gateway-demo-validation` ws server).
+    x-servers: # Based on https://github.com/asyncapi/spec/pull/531
+      - asyncapi-event-gateway-demo
+    publish:
+      message:
+        $ref: '#/components/messages/lightMeasured'
+  event-gateway-demo-validation-events:
+    description: Validation errors are published here, so users can see how message validation happens on the fly based on this right AsyncAPI file.
+    x-servers: # Based on https://github.com/asyncapi/spec/pull/531
+      - asyncapi-event-gateway-demo-validation
+    subscribe:
+      message:
+        $ref: '#/components/messages/ValidationError'
+  event-gateway-demo-validation:
+    description: Validation errors are published to and consumed from it. AsyncAPI Event-gateway is the only user of this channel. It can be consumed and exposed via `event-gateway-demo-validation-events` channel (`asyncapi-event-gateway-demo-validation` ws server).
+    x-servers: # Based on https://github.com/asyncapi/spec/pull/531
+      - asyncapi-kafka-test
+    subscribe:
+      message:
+        $ref: '#/components/messages/ValidationError'
+components:
+  messages:
+    ValidationError:
+      payload:
+        type: object
+        properties:
+          ts:
+            type: string
+            description: RFC-3339 date-time. Date and time when the message was validated.
+          errors:
+            type: array
+            description: Array of string. Validation errors.
+          msg:
+            $ref: '#/components/schemas/Message'
+      examples:
+        - payload:
+            ts: '2021-09-10T12:04:18:475203609Z'
+            errors: [ 'lumens: Invalid type. Expected: integer, given: string' ]
+            msg:
+              context:
+                channel: 'event-gateway-demo'
+              key: 'YXN5bmNhcGktd2FzLWhlcmU='
+              value: 'eyJsdW1lbnMiOiAid2hhdGV2ZXIifQ=='
+    # lightMeasured is copied from the Streetlights tutorial instead of using references due to a bug in parser-go: https://github.com/asyncapi/parser-go/issues/82
+    lightMeasured:
+      name: lightMeasured
+      title: Light measured
+      summary: Inform about environmental lighting conditions of a particular streetlight.
+      contentType: application/json
+      traits:
+        - $ref: '#/components/messageTraits/commonHeaders'
+      payload:
+        $ref: "#/components/schemas/lightMeasuredPayload"
+  schemas:
+    Message:
+      type: object
+      properties:
+        key:
+          type: string
+          description: Kafka message key (base64).
+        value:
+          type: string
+          description: Kafka message value (base64).
+        context:
+          $ref: '#/components/schemas/MessageContext'
+    MessageContext:
+      type: object
+      properties:
+        channel:
+          type: string
+          description: Name of the channel the message was published to.
+    lightMeasuredPayload:
+      type: object
+      properties:
+        lumens:
+          type: integer
+          minimum: 0
+          description: Light intensity measured in lumens.
+        sentAt:
+          $ref: "#/components/schemas/sentAt"
+    sentAt:
+      type: string
+      format: date-time
+      description: Date and time when the message was sent.
+  messageTraits:
+    commonHeaders:
+      headers:
+        type: object
+        properties:
+          my-app-header:
+            type: integer
+            minimum: 0
+            maximum: 100