Skip to content

Commit

Permalink
docs: migrate code generation and message validation tutorials to use…
Browse files Browse the repository at this point in the history 
… Glee (#2317)

Co-authored-by: Alejandra Quetzalli <alejandra.quetzalli@postman.com>
  • Loading branch information
@fmvilas @quetzalliwrites
fmvilas and quetzalliwrites authored Nov 29, 2023
1 parent c77af4d commit cdd2e02
Show file tree
Hide file tree
Showing 2 changed files with 139 additions and 124 deletions.
60 changes: 29 additions & 31 deletions pages/docs/tutorials/generate-code.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Remember>

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`.

</Remember>

## Installation guide
<Remember>
Expand All @@ -24,42 +33,30 @@ import CliInstallation from '../../../assets/docs/fragments/cli-installation.md'

<CliInstallation/>

## 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

<Remember>

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`.

</Remember>

1. Trigger generation of the Node.js code:
1. Trigger the creation of the Glee project:
<CodeBlock language="bash">
{`asyncapi generate fromTemplate asyncapi.yaml @asyncapi/nodejs-template -o output -p server=mosquitto`}
{`asyncapi new glee --name=tutorial --template tutorial`}
</CodeBlock>

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:
<CodeBlock language="bash">
{`cd output && ls`}
{`cd tutorial && ls`}
</CodeBlock>

Upon execution of the command above, the following is an example of the expected result:
<CodeBlock language="bash">
{`$ ls
Dockerfile
asyncapi.yaml
docs
src
LICENSE
README.md
config
asyncapi.yaml
functions
package.json`}
</CodeBlock>

Expand All @@ -71,7 +68,7 @@ If you did not follow the previous tutorial and do not have an `asyncapi.yaml` f

2. Start the application:
<CodeBlock language="bash">
{`npm start`}
{`npm run dev`}
</CodeBlock>

## Send message to broker
Expand All @@ -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:
<CodeBlock language="bash">
{`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.`}
</CodeBlock>
## 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.
203 changes: 110 additions & 93 deletions pages/docs/tutorials/message-validation.md
View file
Original file line number Diff line number Diff line change
@@ -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.
<Remember>

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

</Remember>

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.

<CodeBlock language="bash">
{`npm start`}
</CodeBlock>

2. Let's send a message:

<CodeBlock language="bash">
{`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": "3", "sentAt": "2017-06-07T12:34:32.000Z"}'`}
</CodeBlock>

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:

<CodeBlock language="bash">
{`light/measured was received:
{ id: 1, lumens: '3', sentAt: '2017-06-07T12:34:32.000Z' }
❗ Message Rejected. data.lumens should be integer`}
</CodeBlock>

Here, you can see that the property `lumens` has type `integer`, but you are sending a message with type `string`.

<CodeBlock language="yaml" highlightedLines={[10,11]}>
{` 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.`}
</CodeBlock>

3. Send a correct message to your application:

<CodeBlock language="bash">
{`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'`}
</CodeBlock>

You can see that your generated application received a message in the terminal:

<CodeBlock language="bash">
{`light/measured was received:
{ id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' }`}
</CodeBlock>

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.

<Remember>

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

</Remember>

## 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:

<CodeBlock language="bash">
{`npm run dev`}
</CodeBlock>

2. Send a message:

<CodeBlock language="bash">
{`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": "3", "sentAt": "2017-06-07T12:34:32.000Z"}'`}
</CodeBlock>

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:

<CodeBlock language="bash">
{`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`}
</CodeBlock>

Here, you can see that the property `lumens` has type `integer`, but you are sending a message with type `string`:

<CodeBlock language="yaml" highlightedLines={[10,11]}>
{` 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.`}
</CodeBlock>

3. Send a correct message to your application:

<CodeBlock language="bash">
{`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'`}
</CodeBlock>

You can see that your generated application received a message in the terminal:

<CodeBlock language="bash">
{`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.`}
</CodeBlock>

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).

0 comments on commit cdd2e02

Please sign in to comment.