shifted the code snippet to the start

asyncapi · Nov 12, 2023 · c0eacbb · c0eacbb
1 parent e566cc1
commit c0eacbb
Showing 1 changed file with 41 additions and 39 deletions.
diff --git a/pages/docs/tutorials/configure-asyncapi-kafka.md b/pages/docs/tutorials/configure-asyncapi-kafka.md
@@ -30,65 +30,37 @@ flowchart TD
 
 ## Creating AsyncAPI document for Kafka
 
-In this section, you’ll create an AsyncAPI document to describe the `UserSignUp` API. The same document can be later used to generate code and documentation as per requirement. 
+In this section, you’ll create an AsyncAPI document to describe the `UserSignUp` API. The same document can be later used to generate code and documentation as per requirement.
 
-### Define AsyncAPI version, API information, and server
-
-Initially, you need to describe your application, including the AsyncAPI version, the info about the document, and the server your application is based upon.
+Let's begin by analysing the document. As we move forward in the tutorial, we'll break down each segment uncovering its purpose and functionality.
 
 ```
 asyncapi: 3.0.0
 info:
   title: User Signup API
   version: 1.0.0
   description: The API notifies you whenever a new user signs up in the application.
+
 servers:
   kafkaServer:
     host: test.mykafkacluster.org:8092
     description: Kafka Server
     protocol: kafka
-```
 
-In the above snippet:
-
-- The `asyncapi` field indicates that you are using AsyncAPI version 3.0.0.
-
-- The `info` field provides information about the API. Here the the APIs `title`, `version`, and `description` are being defined.
-
-- The `server` field specifies the details of the server, including the `host`, `description`, and the `protocol` that is being used i.e. Kafka.
-
-### Define channels and operations
-
-Next, let's move on to the `channels` and `operations` section. The channel addresses are the topics in Kafka, they are the routes to which your API will be sending/receiving. The `operations` section is used to describe how your application interacts with the channels.
-
-```
 operations:
   onUserSignedUp:
     action: receive
     channel:
       $ref: '#/channels/userSignedUp'
 
-
 channels:
   userSignedUp:
     description: This channel contains a message per each user who signs up in our application.
     address: user_signedup
     messages:
       userSignedUp:
         $ref: '#/components/messages/userSignedUp'
-```
-
-In the above snippet:
-
-- The `onUserSignedUp` object specifies the nature of the operation. The `action` property indicates that our application will be receiving the information. The `channel` property points to the channel where the operation occurs.
-
-- The `userSignedUp` object inside `channels` describes the Kafka topic where our application will be receiving the information and the associated message definition. The `address` field represents the actual name of the Kafka topic. The `messages` field describes the expected messages in that topic. 
 
-### Define messages and its schemas
-
-Finally, you'll define the messages and their payload. The payload defines how the event would look line that will be sent from the channel.
-
-```
 components:
   messages:
     userSignedUp:
@@ -100,44 +72,68 @@ components:
             description: This property describes the id of the user
           user-email:
             type: string
-            description: This property describes the id of the user
+            description: This property describes the email of the user
 ```
 
-In the above snippet:
+Let's now break it down into pieces:
 
-- The `userSignedUp` message is defined which describes the payload (content) of the message.
-
-- The `payload` property defines the content of the message using [JSON Schema](https://json-schema.org/). It means that your message payload should contain a `user-id` which is an integer and a `user-email` property which is a string property.
+### Define AsyncAPI version, API information, and server
 
-You've reached the end of the tutorial, and piecing together these components will provide you with a fully-prepared AsyncAPI document.
+Initially, you need to describe your application, including the AsyncAPI version, the info about the document, and the server your application is based upon.
 
 ```
 asyncapi: 3.0.0
 info:
   title: User Signup API
   version: 1.0.0
   description: The API notifies you whenever a new user signs up in the application.
-
 servers:
   kafkaServer:
     host: test.mykafkacluster.org:8092
     description: Kafka Server
     protocol: kafka
+```
+
+In the above snippet:
 
+- The `asyncapi` field indicates that you are using AsyncAPI version 3.0.0.
+
+- The `info` field provides information about the API. Here the the APIs `title`, `version`, and `description` are being defined.
+
+- The `server` field specifies the details of the server, including the `host`, `description`, and the `protocol` that is being used i.e. Kafka.
+
+### Define channels and operations
+
+Next, let's move on to the `channels` and `operations` section. The channel addresses are the topics in Kafka, they are the routes to which your API will be sending/receiving. The `operations` section is used to describe how your application interacts with the channels.
+
+```
 operations:
   onUserSignedUp:
     action: receive
     channel:
       $ref: '#/channels/userSignedUp'
 
+
 channels:
   userSignedUp:
     description: This channel contains a message per each user who signs up in our application.
     address: user_signedup
     messages:
       userSignedUp:
         $ref: '#/components/messages/userSignedUp'
+```
 
+In the above snippet:
+
+- The `onUserSignedUp` object specifies the nature of the operation. The `action` property indicates that our application will be receiving the information. The `channel` property points to the channel where the operation occurs.
+
+- The `userSignedUp` object inside `channels` describes the Kafka topic where our application will be receiving the information and the associated message definition. The `address` field represents the actual name of the Kafka topic. The `messages` field describes the expected messages in that topic. 
+
+### Define messages and its schemas
+
+Finally, you'll define the messages and their payload. The payload defines how the event would look line that will be sent from the channel.
+
+```
 components:
   messages:
     userSignedUp:
@@ -149,9 +145,15 @@ components:
             description: This property describes the id of the user
           user-email:
             type: string
-            description: This property describes the email of the user
+            description: This property describes the id of the user
 ```
 
+In the above snippet:
+
+- The `userSignedUp` message is defined which describes the payload (content) of the message.
+
+- The `payload` property defines the content of the message using [JSON Schema](https://json-schema.org/). It means that your message payload should contain a `user-id` which is an integer and a `user-email` property which is a string property.
+
 ## Summary
 
 The ability to generate an AsyncAPI document for Kafka is now in your toolkit. You generated an AsyncAPI document that defines the structure of the Kafka messages in a machine-readable format which makes it easier to maintain event-driven architecture. Try adding your own business logic and playing around with it.