diff --git a/pages/docs/tutorials/generate-code.md b/pages/docs/tutorials/generate-code.md index 0ddf35bd8184..c57d46a25e92 100644 --- a/pages/docs/tutorials/generate-code.md +++ b/pages/docs/tutorials/generate-code.md @@ -6,12 +6,21 @@ weight: 100 ## Introduction -In this tutorial, you'll learn how to generate code from your AsyncAPI document using the AsyncAPI generator tool. +In this tutorial, you'll learn how to generate an application that uses the [Glee](https://github.com/asyncapi/glee) framework. You'll do it with an AsyncAPI document and the [AsyncAPI CLI](/tools/cli). ## Background context -The [AsyncAPI Generator](https://github.com/asyncapi/generator) is a tool that you can use to generate whatever you want based on the AsyncAPI document. You can generate docs and code. It can be used as a library in a Node.js application or through the [AsyncAPI CLI](https://github.com/asyncapi/cli). +[Glee](https://github.com/asyncapi/glee) is a TypeScript/JavaScript framework that enables you to create APIs and messaging clients based on your AsyncAPI document. Instead of generating code, this framework tightly integrates with your AsyncAPI document and binds functions to specific AsyncAPI operations. You only have to provide the code for these functions and Glee handles the rest. -The generator tool supports a number of templates to generate code for a variety of different languages and protocols as the output. These templates help to specify what exactly must be generated, and in this tutorial, you'll use a [Node.js template](https://github.com/asyncapi/nodejs-template). +Glee is often used with the [AsyncAPI CLI](/tools/cli) for a better development experience. + +In the previous tutorial, you created an AsyncAPI document that is used in this tutorial. + + + +If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file for overview, then generate one by running the following command using the AsyncAPI CLI: +`asyncapi new --example=tutorial.yml --no-tty`. + + ## Installation guide @@ -24,42 +33,30 @@ import CliInstallation from '../../../assets/docs/fragments/cli-installation.md' -## Generate code - -To generate code from the [AsyncAPI document created in a previous tutorial](https://asyncapi.com/docs/tutorials/create-asyncapi-document), follow the steps listed below: +## Create a Glee project - - -If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file ready, generate one running `asyncapi new --example=tutorial.yml --no-tty`. - - - -1. Trigger generation of the Node.js code: +1. Trigger the creation of the Glee project: - {`asyncapi generate fromTemplate asyncapi.yaml @asyncapi/nodejs-template -o output -p server=mosquitto`} + {`asyncapi new glee --name=tutorial --template tutorial`} Let's break down the previous command: - - `asyncapi generate fromTemplate` is how you use AsyncAPI Generator via the AsyncAPI CLI. - - ` asyncapi.yaml` is how you point to your AsyncAPI document and can be a URL. - - `@asyncapi/nodejs-template` is how you specify the Node.js template. - - `-o` determines where to output the result. - - `-p` defines additional parameters you want to pass to the template. Here, the `server` parameter specifies the server's name as it is defined in AsyncAPI document. + - `asyncapi new glee` is how you use Glee via the AsyncAPI CLI. + - `--name=tutorial` is how you tell the AsyncAPI CLI to name your new Glee project. + - `--template=tutorial` is how you tell the AsyncAPI CLI to use the template of a Glee project that was created specifically for this tutorial. -2. List all files in directory and check that the Node.js application is generated: +2. List all files in the directory and confirm your Glee project creation: - {`cd output && ls`} + {`cd tutorial && ls`} Upon execution of the command above, the following is an example of the expected result: {`$ ls - Dockerfile - asyncapi.yaml - docs - src + LICENSE README.md - config + asyncapi.yaml + functions package.json`} @@ -71,7 +68,7 @@ If you did not follow the previous tutorial and do not have an `asyncapi.yaml` f 2. Start the application: - {`npm start`} + {`npm run dev`} ## Send message to broker @@ -87,13 +84,14 @@ If you did not follow the previous tutorial and do not have an `asyncapi.yaml` f 3. Go back to the previous terminal to check if your application logged the streetlight condition you just sent. You should see something like this displayed in the terminal: - {`light/measured was received: - { id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' }`} + {`lightMeasured was received from mosquitto: + { id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' } + Streetlight with id "1" updated its lighting information to 3 lumens at 2017-06-07T12:34:32.000Z.`} ## Summary -In this tutorial, you learned how to generate your code from the [Streetlights API specification document created in a previous tutorial](https://asyncapi.com/docs/tutorials/create-asyncapi-document) using the AsyncAPI generator tool. +In this tutorial, you learned how to create a Glee project from the [Streetlights API specification document created in a previous tutorial](https://asyncapi.com/docs/tutorials/create-asyncapi-document). -Additionally, you've learned how to run your code by installing the generated code's dependencies and sending several test messages to the Streelights application using the MQTT client. +Additionally, you've learned how to run your code by installing the project's dependencies and sending several test messages to the Streelights application using the MQTT client. ## Next steps Now that you've completed this tutorial, go ahead and learn how to [validate your AsyncAPI messages (events)](https://asyncapi.com/docs/tutorials/message-validation) through the message validation techniques supported by AsyncAPI. diff --git a/pages/docs/tutorials/message-validation.md b/pages/docs/tutorials/message-validation.md index e06d226b291f..faea57f4a730 100644 --- a/pages/docs/tutorials/message-validation.md +++ b/pages/docs/tutorials/message-validation.md @@ -1,93 +1,110 @@ ---- -title: Message validation in runtime -description: In this tutorial, you'll learn how to validate AsyncAPI messages (events). - -weight: 130 ---- - -## Introduction -In this tutorial, you'll learn how to validate messages (events) that are sent to your AsyncAPI application. - -## Background context -Message validation can be performed at both the **producer** and **consumer** levels. Message validation requires the participation of the producer, consumer, and broker. We will learn how to validate messages at the consumer level by discarding invalid messages based on the parameters provided. - -You will be using the [Eclipse Mosquitto](https://mosquitto.org/) broker. The MQTT protocol provides a lightweight method of messaging using a publish/subscribe model. You will also use an MQTT client that runs an MQTT library and connects to an MQTT broker over a network. Here publishers and subscribers are MQTT clients. The publisher and subscriber labels refer to whether the client is publishing or subscribing to receive messages. - -In the previous tutorial, you generated your application using the [AsyncAPI Generator](https://github.com/asyncapi/generator) Node.js template. - - -If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file ready, then generate one by running: -`asyncapi new --example=tutorial.yml --no-tty`. - -Next, generate a server by running: - - asyncapi generate fromTemplate asyncapi.yaml @asyncapi/nodejs-template -o output -p server=mosquitto - cd output && npm install - - - -Now you will be validating the messages which you will be sending to your application using a Mosquitto broker and an MQTT client. - -## Validate messages -In this step, you will send a message to your application using an MQTT broker and check the errors logged when you accidentally send an invalid message. - -1. Start your generated application. - - -{`npm start`} - - -2. Let's send a message: - - - {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": "3", "sentAt": "2017-06-07T12:34:32.000Z"}'`} - - -Go back to the previous terminal and check if your application logged the streetlight condition you just sent, with errors related to the invalid message. You should see something displayed in the terminal similar to the following: - - - {`light/measured was received: -{ id: 1, lumens: '3', sentAt: '2017-06-07T12:34:32.000Z' } -❗ Message Rejected. data.lumens should be integer`} - - -Here, you can see that the property `lumens` has type `integer`, but you are sending a message with type `string`. - - - {` message: - name: lumensInfo - 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.`} - - -3. Send a correct message to your application: - - - {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'`} - - -You can see that your generated application received a message in the terminal: - - - {`light/measured was received: -{ id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' }`} - - -This indicates that your message is valid and the application recieved it correctly. - -## Summary -In this tutorial, you learned how to connect your generated application to an MQTT broker, send messages through it, identify when an invalid message is sent to your application, and how to correct an invalid message. - -## Next steps -Now that you've completed this tutorial, enjoy our [AsyncAPI message validation guide](https://www.asyncapi.com/docs/guides/message-validation). - ---- +--- +title: Message validation in runtime +description: In this tutorial, you'll learn how to validate AsyncAPI messages (events). + +weight: 130 +--- + +## Introduction +In this tutorial, you'll learn how to validate messages (events) that are sent to your AsyncAPI application. + +## Background context +Message validation can be performed at both the **producer** and **consumer** levels. Message validation requires the participation of the producer, consumer, and broker. We will learn how to validate messages at the consumer level by discarding invalid messages based on the parameters provided. + +You will be using the [Eclipse Mosquitto](https://mosquitto.org/) broker. The MQTT protocol provides a lightweight method of messaging using a publish/subscribe model. You will also use an MQTT client that runs an MQTT library and connects to an MQTT broker over a network. Here producers and consumers are MQTT clients. The producer and consumer labels refer to whether the client is sending or receiving messages. + +In the [previous tutorial, you generated an application](https://asyncapi.com/docs/tutorials/generate-code) that uses [Glee](https://github.com/asyncapi/glee) framework. Now you will be validating the messages that you will be sending to your application using a Mosquitto broker and an MQTT client. + + + +If you did not follow the previous tutorial and do not have an application generated, then follow these instructions: + + asyncapi new glee --name=tutorial --template tutorial`. + cd tutorial && npm install + + + +## Validate messages +In this step, you will send a message to your application using an MQTT broker and check the errors logged when you accidentally send an invalid message. + +1. Start your generated application: + + +{`npm run dev`} + + +2. Send a message: + + + {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": "3", "sentAt": "2017-06-07T12:34:32.000Z"}'`} + + +Go back to the previous terminal and check if your application logged the streetlight condition you just sent, with errors related to the invalid message. You should see something displayed in the terminal similar to the following: + + + {`lightMeasured was received from mosquitto: +{ id: 1, lumens: '3', sentAt: '2017-06-07T12:34:32.000Z' } +x You have received a malformed event or there has been error processing it. Please review the error below: +TYPE should be integer + + 1 | { + 2 | "id": 1, +> 3 | "lumens": "3", + | ^^^ 👈🏽 type should be integer + 4 | "sentAt": "2017-06-07T12:34:32.000Z" + 5 | } + +ONEOF should match exactly one schema in oneOf + +> 1 | { + | ^ +> 2 | "id": 1, + | ^^^^^^^^^^ +> 3 | "lumens": "3", + | ^^^^^^^^^^ +> 4 | "sentAt": "2017-06-07T12:34:32.000Z" + | ^^^^^^^^^^ +> 5 | } + | ^^ 👈🏽 oneOf should match exactly one schema in oneOf`} + + +Here, you can see that the property `lumens` has type `integer`, but you are sending a message with type `string`: + + + {` message: + name: lumensInfo + 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.`} + + +3. Send a correct message to your application: + + + {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'`} + + +You can see that your generated application received a message in the terminal: + + + {`lightMeasured was received from mosquitto: +{ id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' } +Streetlight with id "1" updated its lighting information to 3 lumens at 2017-06-07T12:34:32.000Z.`} + + +Such a terminal message indicates that your message is valid and the application received it correctly. + +## Summary +In this tutorial, you learned how to connect your generated application to an MQTT broker, send messages through it, identify when an invalid message is sent to your application, and how to correct an invalid message. + +## Next steps +Now that you've completed this tutorial, enjoy our [AsyncAPI message validation guide](https://www.asyncapi.com/docs/guides/message-validation). +