updates

derberg · Jul 13, 2022 · 8b2fac8 · 8b2fac8
1 parent 783f6a5
commit 8b2fac8
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 7 deletions.
diff --git a/scripts/asyncapi-intro.md b/scripts/asyncapi-intro.md
@@ -17,15 +17,90 @@
   - AsyncAPI is for describing the application interface, not the broker
   - EDA is not broker only, thus AsyncAPI is not only for broker-centric architectures
   - Channels are topics
-  - Publish/subscribe operations
+  - [Publish/subscribe](https://www.asyncapi.com/blog/publish-subscribe-semantics) operations
 
 #### Flexibility
 
   - Protocol agnostic aka [`bindings` feature](https://github.com/asyncapi/bindings). Like with [MQTT](https://github.com/asyncapi/bindings/tree/master/mqtt) when you connect to it, [`clientId`](https://github.com/asyncapi/spec/blob/v2.4.0/examples/social-media/comments-service/asyncapi.yaml#L14) must be provieded
-  - Multiple message schema formats aka `"Just reuse what you already have defined in other systems"` -> [AsyncAPI](https://www.asyncapi.com/docs/specifications/v2.4.0#schemaObject), [JSON Schema](https://json-schema.org/), [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#data-types), [RAML DT](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#raml-data-types), [Avro](https://avro.apache.org/docs/current/spec.html)
+  - Multiple message schema formats (`schemaFormat`) aka `"Just reuse what you already have defined in other systems"` -> [AsyncAPI Schema](https://www.asyncapi.com/docs/specifications/v2.4.0#schemaObject), [JSON Schema](https://json-schema.org/), [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#data-types), [RAML DT](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#raml-data-types), [Avro](https://avro.apache.org/docs/current/spec.html)
+      ```
+      //example message data - GOOD
+      {
+        "displayName": "Shrek from the swamp",
+        "email": "[email protected]",
+        "age": 39
+      }
+      //example message data - BAD
+      {
+        "displayName": "Shrek from the swamp",
+        "email": "[email protected]",
+        "age": "39y"
+      }
+      ```
+      ```
+      //json schema
+      {
+        "description" : "User information",
+        "type" : "object",
+        "additionalProperties": false,
+        "properties" : {
+          "displayName" : {
+            "type" : "string"
+          },
+          "email" : {
+            "type" : "string"
+          },
+          "age" : {
+            "type" : "integer",
+          }
+       }
+      }   
+      ```
+      ```
+      //asyncapi schema
+      {
+        "description" : "**User** information",
+        "type" : "object",
+        "additionalProperties": false,
+        "properties" : {
+          "displayName" : {
+            "type" : "string"
+          },
+          "email" : {
+            "type" : "string"
+          },
+          "age" : {
+            "type" : "integer",
+          }
+       }
+      }   
+      ```
+      ```
+      //avro
+      {
+        "type": "record",
+        "name": "User",
+        "namespace": "com.company",
+        "doc": "User information",
+        "fields": [
+          {
+            "name": "displayName",
+            "type": "string"
+          },
+          {
+            "name": "email",
+            "type": "string"
+          },
+          {
+            "name": "age",
+            "type": "int"
+          }
+        ]
+      }
+      ```
   - Extensibility through `x-` properties. Useful when there is something not available in the spec, like [specifying a response](https://www.asyncapi.com/blog/websocket-part2#describe-responses---specification-extensions)
   
 #### Info structure optimization
 
   - Traits for common info inside AsyncAPI document. Like with [this Kafka example](https://github.com/asyncapi/spec/blob/v2.4.0/examples/streetlights-kafka.yml#L159)
-  - Sharing of information between components and files with [JSON References](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03) as in [this social media example](https://github.com/asyncapi/spec/blob/v2.4.0/examples/social-media/comments-service/asyncapi.yaml)
+  - Sharing of information between components and files with [JSON References](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03)(`$ref`) as in [this social media example](https://github.com/asyncapi/spec/blob/v2.4.0/examples/social-media/comments-service/asyncapi.yaml)
diff --git a/scripts/asyncapi-step-by-step.md b/scripts/asyncapi-step-by-step.md
@@ -14,7 +14,7 @@ Yes, just joking, no human would choose JSON...right?
 We release regularly every few months. Learn more from [official release process instruction](https://github.com/asyncapi/spec/blob/master/RELEASE_PROCESS.md).
 
 ```yaml
-asyncapi: 2.4.0
+asyncapi: 2.4.0 #https://github.com/asyncapi/spec/releases
 ```
 
 ### 4. Provide overal info about the App
@@ -40,6 +40,8 @@ servers:
     protocol: ws
 ```
 
+> Sometimes it is the server that points directly to the app (WebSocket) but can also be a remote server, broker address.
+
 ### 6. What are the communication channels
 
 In case of WebSockets you could say these are like endpoints. In case of most broker-centric architecture they are also called topics.
@@ -79,7 +81,7 @@ components:
                 type: string
             arrival:
                 description: Time left to get there.
-            t   type: string
+                type: string
 ```
 
 and now reference inside the message.
@@ -89,7 +91,8 @@ components:
   messages:
     travelInfo:
       summary: Message that contains information about travel status.
-      payload: "#/components/schemas/travelData"
+      payload: 
+        $ref: "#/components/schemas/travelData"
       examples:
         - payload:
             destination: Far far away

diff --git a/scripts/asyncapi-usage.md b/scripts/asyncapi-usage.md
@@ -9,11 +9,17 @@ So you went through the hell of:
 **Do not stop with docs**
 
 - Real-time message validation
-- Broker Operations
+  - https://github.com/WaleedAshraf/asyncapi-validator
+  - https://github.com/asyncapi/event-gateway/
 - Discoverability of traffic
+  - https://github.com/asyncapi/spec/tree/master/examples/social-media
 - Design-first!
 - Prototyping and testing
+  - Look at https://microcks.io/
+  - or https://github.com/asyncapi/simulator
 - Code generation
+  - `asyncapi generate models typescript asyncapi.yml`
+  - https://github.com/derberg/shrekapp-asyncapi-designed ([See this video to understang how this project was created](https://youtu.be/PPeRnEaqBW8?t=920))
 - Self-service platforms
 
 Just to name few...