diff --git a/pages/docs/tutorials/configure-asyncapi-kafka.md b/pages/docs/tutorials/configure-asyncapi-kafka.md index 06bc90d04d0..b83132a5a62 100644 --- a/pages/docs/tutorials/configure-asyncapi-kafka.md +++ b/pages/docs/tutorials/configure-asyncapi-kafka.md @@ -30,11 +30,9 @@ 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 @@ -42,33 +40,19 @@ 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. @@ -76,19 +60,7 @@ channels: 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,16 +72,14 @@ 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 @@ -117,19 +87,33 @@ 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. @@ -137,7 +121,19 @@ channels: 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.