docs: re-add Create AsyncAPI document

pages/docs/tutorials/create-asyncapi-document.md

@@ -0,0 +1,183 @@
+---
+title: Create AsyncAPI document
+description: In this tutorial, you'll learn how to create an AsyncAPI document.
+weight: 80
+---
+
+## Introduction
+
+In this tutorial, you'll learn how to create an AsyncAPI document based on a sample real-world use case. Additionally, you will learn about event-driven architecture, message brokers, pub/sub pattern.
+
+Let's pretend you have a company called Smarty Lighting, and you install smart-city streetlight lighting systems. This smart lighting system is a use case of the Internet of Things (IoT). You will create a Smarty Lighting Streetlights application using Node.js and Mosquitto (MQTT) as the message broker. This application will allow you to manage city lights remotely. 
+
+You want to build a system that can turn streetlights on and off based on their environmental conditions: 
+
+- You will implement an event-driven architecture (EDA) with a message broker in its "center."
+
+- Streetlights application will receive information about environmental lighting.
+
+- Streetlights application will connect to the broker and receive a stream of events from all the streetlights devices reporting their conditions.
+
+- Streetlights application is not aware of how many streetlights devices are sending measurement events to the broker - it just connects to the broker and receives all events.
+
+
+## Background context
+
+Event-driven architecture (EDA) is a design pattern built around the production, detection, and reaction to events that take place in time. In this pattern, a message broker, event publishers and subscribers are its main components for event exchange within microservices.
+
+[Message brokers](/docs/tutorials/getting-started/event-driven-architectures#message-broker) enables asynchronous communications between services so that the sending service need not wait for the receiving service’s reply. This allows interdependent services to “talk” with one another directly, even if they were written in different languages or implemented on different platforms. 
+
+Furthermore, the [Pub/sub](/docs/tutorials/getting-started/event-driven-architectures#publishersubscriber) is appealing for IoT use cases due to two key features: support for flexible coupling between publishers/subscribers and inherent support for point-to-multipoint transmission.  
+
+[MQTT](https://mqtt.org/), is a well-known protocol that is widely used in IoT applications because it was created particularly to address machine-to-machine (M2M) communication.
+
+## Create AsyncAPI document
+
+In this step, you will create an AsyncAPI document to describe the Streelights application. It will help you generate the code and the documentation later on.
+
+To create one, you can either use the [AsyncAPI Studio](https://studio.asyncapi.com) or the [AsyncAPI CLI](https://github.com/asyncapi/cli), depending on your project's needs..
+
+<Remember>
+
+You can create a new `asyncapi.yaml` document by running: 
+`asyncapi new --example=tutorial.yml --no-tty`.
+
+</Remember>
+
+Go ahead to create the specification documents titled `asyncapi` with a `.yaml` extension.
+
+<CodeBlock>
+{`asyncapi: 3.0.0
+info:
+  title: Streetlights App
+  version: '1.0.0'
+  description: |
+    The Smartylighting Streetlights application allows you
+    to remotely manage the city lights.
+  license:
+    name: Apache 2.0
+    url: 'https://www.apache.org/licenses/LICENSE-2.0'
+servers:
+  mosquitto:
+    host: test.mosquitto.org
+    protocol: mqtt
+channels:
+  lightMeasured:
+    address: 'light/measured'
+    messages:
+      lightMeasuredMessage:
+        name: LightMeasured
+        payload:
+          type: object
+          properties:
+            id:
+              type: integer
+              minimum: 0
+              description: Id of the streetlight.
+            lumens:
+              type: integer
+              minimum: 0
+              description: Light intensity measured in lumens.
+            sentAt:
+              type: string
+              format: date-time
+              description: Date and time when the message was sent.
+operations:
+  onLightMeasured:
+    action: 'receive'
+    summary: Information about environmental lighting conditions for a particular streetlight.
+    channel:
+      $ref: '#/channels/lightMeasured'`}
+</CodeBlock>
+
+Let's break it down into pieces:
+
+<CodeBlock>
+{`asyncapi: 3.0.0
+info:
+  title: Streetlights App
+  version: '1.0.0'
+  description: |
+    The Smartylighting Streetlights application allows you
+    to remotely manage the city lights.
+  license:
+    name: Apache 2.0
+    url: 'https://www.apache.org/licenses/LICENSE-2.0'`}
+</CodeBlock>
+
+- The `asyncapi` field indicates you use the AsyncAPI version 3.0.0.
+
+- The `info` field holds information about the Streetlights application. Here, the title, version, description and license were defined.
+
+Moving on, let's talk about the `servers` section.
+<CodeBlock>
+{`servers:
+  mosquitto:
+    host: test.mosquitto.org
+    protocol: mqtt`}
+</CodeBlock> 
+
+In this section, you point to the Eclipse Mosquitto message broker. The `url` point to a real instance of the broker [hosted by the Mosquitto community](https://test.mosquitto.org/) and the `protocol` as MQTT. If you do not want to use the test instance, you can spin up your own broker locally with `docker run -it -p 1883:1883 eclipse-mosquitto:1.5`. But remember to change `url` to `mqtt://localhost`
+
+Now lets move on to the `channels` section. In `servers` section you specified how to connect to the broker where the application sends messages to or receive messages from. In `channels` you go more into details of connection `address` inside the broker, like for example topic name, and you specify what `messages` are available in the channel.
+
+<CodeBlock>
+{`channels:
+  lightMeasured:
+    address: 'light/measured'
+    messages:
+      lightMeasuredMessage:
+        name: LightMeasured
+        payload:
+          #dedacted for brevity`}
+</CodeBlock>
+
+In this example, `light/measured` is the channel address. From perspective of the Streetlight application example it means that `light/measured` is the name of the topic in the MQTT broker.
+
+Next is the `payload` property, which is used to understand how the event should look like when transfered over the specific channel:
+
+<CodeBlock>
+{`      payload:
+        type: object
+        properties:
+          id:
+            type: integer
+            minimum: 0
+            description: Id of the streetlight.
+          lumens:
+            type: integer
+            minimum: 0
+            description: Light intensity measured in lumens.
+          sentAt:
+            type: string
+            format: date-time
+            description: Date and time when the message was sent.`}
+</CodeBlock>
+
+The `payload` property defines the content of the event using AsyncAPI schemas. It means that your event payload should contain an `id` and a `lumens` property —which are integers bigger than zero—, and a `sentAt` property that should be a string containing a date and time.
+
+>  JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, like, for example [Avro](https://github.com/asyncapi/avro-schema-parser#usage).
+
+Last section is `operations` where you describe what is the application described with AsyncAPI document doing. It it a consumer that receives messages from the broker or maybe producer sending messages to the broker, or both?
+
+<CodeBlock>
+{`operations:
+  onLightMeasured:
+    action: 'receive'
+    summary: Information about environmental lighting conditions for a particular streetlight.
+    channel:
+      $ref: '#/channels/lightMeasured'`}
+</CodeBlock>
+
+You can see that the Streetlight application is a consumer that only receives events from the broker. By using mandatory `channel` field, you specify with `$ref` what channel with the events come from.
+
+The `onLightMeasured` key property describes what is the name of function or method that takes care of this functionality in the generated code. It is a unique ID of the operation across the whole document.
+
+## Summary
+
+In this tutorial, you learned how to create an AsyncAPI specification document via a real-life example with an IoT use case.
+
+This tutorial is just a starting point; you'll need to add your own business logic to it. Take some time to play with it. There are still lots of things to be covered, but the intent of this tutorial is to make it simple for you to get an idea of the potential.
+
+## Next steps
+Now that you've completed this tutorial, proceed to learn how to [validate your AsyncAPI document with AsyncAPI Studio](https://www.asyncapi.com/docs/tutorials/studio-document-validation).