docs: update examples to be written by human not converter (#977)

asyncapi · Oct 30, 2023 · cc109fe · cc109fe
1 parent abfae49
commit cc109fe
Show file tree

Hide file tree

Showing 26 changed files with 312 additions and 260 deletions.
diff --git a/examples/README.md b/examples/README.md
@@ -2,4 +2,14 @@
 
 In this directory, you can find some examples of AsyncAPI documents.
 
-**Do you have an example that could be valuable?** Open a pull request to contribute it.
+**Do you have an example that could be valuable?** Open a pull request to contribute it.
+
+## File naming
+
+You may notice `asyncapi` in the the name of each example. We recommend doing the same with your AsyncAPI document. This way you enable features like documentation display on node hover, auto completion and validation of your AsyncAPI documents in IDEs like VSCode or IntelliJ IDEA. IDEs integrate with [SchemaStore](https://www.schemastore.org/json/) where AsyncAPI specification JSON Schema files are referenced. Some IDEs do it by default, some, like VSCode require you to install additional extensions, like `YAML` extension.
+
+## Editors
+
+To edit your AsyncAPI documents, you can use [AsyncAPI Studio](https://studio.asyncapi.com/).
+
+If you prefer to use your favourite IDE, there are official extensions for [VSCode](https://marketplace.visualstudio.com/items?itemName=asyncapi.asyncapi-preview) and [IntelliJ IDEA](https://plugins.jetbrains.com/plugin/15673-asyncapi)
diff --git a/examples/adeo-kafka-request-reply.yml → ...les/adeo-kafka-request-reply-asyncapi.yml b/examples/adeo-kafka-request-reply.yml → ...les/adeo-kafka-request-reply-asyncapi.yml
diff --git a/examples/anyof.yml → examples/anyof-asyncapi.yml b/examples/anyof.yml → examples/anyof-asyncapi.yml
@@ -33,4 +33,4 @@ components:
       type: object
       properties:
         key2:
-          type: string
+          type: string
diff --git a/examples/application-headers.yml → examples/application-headers-asyncapi.yml b/examples/application-headers.yml → examples/application-headers-asyncapi.yml
@@ -20,10 +20,10 @@ servers:
           - '1883'
           - '8883'
 channels:
-  'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured':
+  lightingMeasured:
     address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
     messages:
-      receiveLightMeasurement.message:
+      lightMeasured:
         $ref: '#/components/messages/lightMeasured'
     parameters:
       streetlightId:
@@ -32,8 +32,7 @@ operations:
   receiveLightMeasurement:
     action: receive
     channel:
-      $ref: >-
-        #/channels/smartylighting~1streetlights~11~10~1event~1{streetlightId}~1lighting~1measured
+      $ref: '#/channels/lightingMeasured'
     summary: >-
       Inform about environmental lighting conditions of a particular
       streetlight.
@@ -84,4 +83,4 @@ components:
       type: string
   parameters:
     streetlightId:
-      description: The ID of the streetlight.
+      description: The ID of the streetlight.
diff --git a/examples/correlation-id.yml → examples/correlation-id-asyncapi.yml b/examples/correlation-id.yml → examples/correlation-id-asyncapi.yml
@@ -56,18 +56,18 @@ servers:
           - 'streetlights:dim'
       - $ref: '#/components/securitySchemes/openIdConnectWellKnown'
 channels:
-  'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured':
+  lightingMeasured:
     address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
     messages:
-      receiveLightMeasurement.message:
+      lightMeasured:
         $ref: '#/components/messages/lightMeasured'
     parameters:
       streetlightId:
         $ref: '#/components/parameters/streetlightId'
-  'smartylighting/streetlights/1/0/action/{streetlightId}/dim':
+  lightsDim:
     address: 'smartylighting/streetlights/1/0/action/{streetlightId}/dim'
     messages:
-      dimLight.message:
+      dimLight:
         $ref: '#/components/messages/dimLight'
     parameters:
       streetlightId:
@@ -76,8 +76,7 @@ operations:
   receiveLightMeasurement:
     action: receive
     channel:
-      $ref: >-
-        #/channels/smartylighting~1streetlights~11~10~1event~1{streetlightId}~1lighting~1measured
+      $ref: '#/channels/lightingMeasured'
     summary: >-
       Inform about environmental lighting conditions of a particular
       streetlight.
@@ -86,8 +85,7 @@ operations:
   dimLight:
     action: send
     channel:
-      $ref: >-
-        #/channels/smartylighting~1streetlights~11~10~1action~1{streetlightId}~1dim
+      $ref: '#/channels/lightsDim'
     messages:
       - $ref: '#/components/messages/dimLight'
 components:
@@ -179,4 +177,4 @@ components:
             'streetlights:dim': Ability to dim the lights
     openIdConnectWellKnown:
       type: openIdConnect
-      openIdConnectUrl: 'https://authserver.example/.well-known'
+      openIdConnectUrl: 'https://authserver.example/.well-known'
diff --git a/examples/gitter-streaming.yml → examples/gitter-streaming-asyncapi.yml b/examples/gitter-streaming.yml → examples/gitter-streaming-asyncapi.yml
@@ -12,12 +12,12 @@ servers:
     security:
       - $ref: '#/components/securitySchemes/httpBearerToken'
 channels:
-  '/rooms/{roomId}/{resource}':
+  rooms:
     address: '/rooms/{roomId}/{resource}'
     messages:
-      subscribe.message.0:
+      chatMessage:
         $ref: '#/components/messages/chatMessage'
-      subscribe.message.1:
+      heartbeat:
         $ref: '#/components/messages/heartbeat'
     parameters:
       roomId:
@@ -30,10 +30,10 @@ channels:
           - events
         description: The resource to consume.
 operations:
-  '/rooms/{roomId}/{resource}.subscribe':
+  sendRoomInfo:
     action: send
     channel:
-      $ref: '#/channels/~1rooms~1{roomId}~1{resource}'
+      $ref: '#/channels/rooms'
     bindings:
       http:
         type: response
@@ -148,7 +148,15 @@ components:
               description: Stands for "Gravatar version" and is used for cache busting.
       bindings:
         http:
-          $ref: '#/components/messageBindings/streamingHeaders'
+          headers:
+            type: object
+            properties:
+              Transfer-Encoding: 
+                type: string
+                const: chunked
+              Trailer: 
+                type: string
+                const: \r\n
     heartbeat:
       summary: Its purpose is to keep the connection alive.
       payload:
@@ -159,10 +167,12 @@ components:
             - "\r\n"
       bindings:
         http:
-          $ref: '#/components/messageBindings/streamingHeaders'
-  messageBindings:
-    streamingHeaders:
-      http:
-        headers:
-          Transfer-Encoding: chunked
-          Trailer: \r\n
+          headers:
+            type: object
+            properties:
+              Transfer-Encoding: 
+                type: string
+                const: chunked
+              Trailer: 
+                type: string
+                const: \r\n
diff --git a/...request-reply-message-filter-in-reply.yml → ...eply-message-filter-in-reply-asyncapi.yml b/...request-reply-message-filter-in-reply.yml → ...eply-message-filter-in-reply-asyncapi.yml
@@ -36,76 +36,107 @@ channels:
         $ref: '#/components/messages/subscribe'
       unsubscribe:
         $ref: '#/components/messages/unsubscribe'
+      dummyCurrencyInfo:
+        $ref: '#/components/messages/dummyCurrencyInfo'
 
 
 operations:
-  pingPong:
-    action: send
+  receivePing:
+    action: receive
     channel: 
       $ref: '#/channels/currencyExchange'
     reply:
       channel: 
         $ref: '#/channels/currencyExchange'
       messages:
-        - $ref: '#/components/messages/ping'
-  heartbeat:
-    action: receive
+        - $ref: '#/components/messages/pong'
+    messages:
+      - $ref: '#/components/messages/ping'
+  sendHeartbeat:
+    action: send
     channel: 
-      $ref: '#/channels/currencyExchange' 
+      $ref: '#/channels/currencyExchange'
+    messages:
+      - $ref: '#/components/messages/heartbeat'
   systemStatus:
-    action: receive
-    channel: 
-      $ref: '#/channels/currencyExchange' 
-  subscribe:
     action: send
+    channel: 
+      $ref: '#/channels/currencyExchange'
+    messages:
+      - $ref: '#/components/messages/systemStatus'
+  receiveSubscribeRequest:
+    action: receive
     channel: 
       $ref: '#/channels/currencyExchange'
     reply:
       channel: 
         $ref: '#/channels/currencyExchange'
       messages:
         - $ref: '#/components/messages/subscriptionStatus'
-  unsubscribe:
-    action: send
+        - $ref: '#/components/messages/dummyCurrencyInfo'
+    messages:
+      - $ref: '#/components/messages/subscribe'
+  receiveUnsubscribeRequest:
+    action: receive
     channel: 
       $ref: '#/channels/currencyExchange'
     reply:
       channel: 
         $ref: '#/channels/currencyExchange'   
       messages:
         - $ref: '#/components/messages/subscriptionStatus'
+    messages:
+      - $ref: '#/components/messages/unsubscribe'
 
 
 components:
   messages:
+    dummyCurrencyInfo:
+      summary: Dummy message with no real life details
+      description: It is here in this example to showcase that there is an additional message that normally is of a complex structure. It represents actually currency exchange value to show a reply to operation receiveSubscribeRequest with more than one possible message.
+      payload:
+        type: object
+        properties:
+          event:
+            type: string
+            const: currencyInfo
+          reqid:
+            $ref: '#/components/schemas/reqid'
+          data:
+            type: object
+        required:
+          - event
+      correlationId:
+        location: '$message.payload#/reqid'
+
     ping:
       summary: Ping server to determine whether connection is alive
       description: Client can ping server to determine whether connection is alive, server responds with pong. This is an application level ping as opposed to default ping in websockets standard which is server initiated
       payload:
         $ref: '#/components/schemas/ping'
       correlationId:
-        location: $message.payload#/reqid
+        location: '$message.payload#/reqid'
 
     pong:
       summary: Pong is a response to ping message
       description: Server pong response to a ping to determine whether connection is alive. This is an application level pong as opposed to default pong in websockets standard which is sent by client in response to a ping
       payload:
         $ref: '#/components/schemas/pong' 
       correlationId:
-        location: $message.payload#/reqid
+        location: '$message.payload#/reqid'
 
     subscribe:
       description: Subscribe to a topic on a single or multiple currency pairs.
       payload:
         $ref: '#/components/schemas/subscribe'
       correlationId:
-        location: $message.payload#/reqid
+        location: '$message.payload#/reqid'
     unsubscribe:
       description: Unsubscribe, can specify a channelID or multiple currency pairs.
       payload:
         $ref: '#/components/schemas/unsubscribe'
       correlationId:
-        location: $message.payload#/reqid
+        location: '$message.payload#/reqid'
     subscriptionStatus:
       description: Subscription status response to subscribe, unsubscribe or exchange initiated unsubscribe.
       payload:

diff --git a/...ocket-request-reply-multiple-channels.yml → ...uest-reply-multiple-channels-asyncapi.yml b/...ocket-request-reply-multiple-channels.yml → ...uest-reply-multiple-channels-asyncapi.yml
@@ -42,57 +42,79 @@ channels:
       systemStatus:
         $ref: '#/components/messages/systemStatus'
 
-  subscriptionStatus:
+  currencyInfo:
     address: /
     messages:
       subscriptionStatus:
         $ref: '#/components/messages/subscriptionStatus'
+      dummyCurrencyInfo:
+        $ref: '#/components/messages/dummyCurrencyInfo'
+
   subscribe:
     address: /
     messages:
       subscribe:
         $ref: '#/components/messages/subscribe'
+
   unsubscribe:
     address: /
     messages:
       unsubscribe:
         $ref: '#/components/messages/unsubscribe'
-
 
 operations:
-  pingPong:
-    action: send
+  receivePing:
+    action: receive
     channel: 
       $ref: '#/channels/ping'
     reply:
       channel: 
         $ref: '#/channels/pong'
   heartbeat:
-    action: receive
+    action: send
     channel: 
       $ref: '#/channels/heartbeat' 
   systemStatus:
-    action: receive
+    action: send
     channel: 
       $ref: '#/channels/systemStatus' 
   subscribe:
-    action: send
+    action: receive
     channel: 
       $ref: '#/channels/subscribe'
     reply:
       channel: 
-        $ref: '#/channels/subscriptionStatus'
+        $ref: '#/channels/currencyInfo'
   unsubscribe:
-    action: send
+    action: receive
     channel: 
       $ref: '#/channels/unsubscribe'
     reply:
       channel: 
-        $ref: '#/channels/subscriptionStatus'   
+        $ref: '#/channels/currencyInfo'
+      messages:
+        - $ref: '#/components/messages/subscriptionStatus'   
 
 
 components:
   messages:
+    dummyCurrencyInfo:
+      summary: Dummy message with no real life details
+      description: It is here in this example to showcase that there is an additional message that normally is of a complex structure. It represents actually currency exchange value to show a reply to operation receiveSubscribeRequest with more than one possible message.
+      payload:
+        type: object
+        properties:
+          event:
+            type: string
+            const: currencyInfo
+          reqid:
+            $ref: '#/components/schemas/reqid'
+          data:
+            type: object
+        required:
+          - event
+      correlationId:
+        location: '$message.payload#/reqid'
     ping:
       summary: Ping server to determine whether connection is alive
       description: Client can ping server to determine whether connection is alive, server responds with pong. This is an application level ping as opposed to default ping in websockets standard which is server initiated