AsyncAPI Tools

In my previous post, I talked about basic of AsyncAPI. In this post, I want to get into more details on some tools around AsyncAPI.

More specially, we’ll install AsyncAPI CLI and Generator, generate a sample AsyncAPI definition, visualize it in AsyncAPI Studio, and generate code from it. You’ll see how useful AsyncAPI can be in documenting and maintaining your event-driven architectures.

Install AsyncAPI tools

First, let’s install some of the AsyncAPI tools.

AsyncAPI CLI is a CLI tool to create, validate, and explore your AsyncAPI files.

You can install it with brew or npm:

npm install -g @asyncapi/cli

AsyncAPI Generator is another CLI tool to generate documentation and code from your AsyncAPI files.

You can install it with npm:

npm install -g @asyncapi/generator

Install the client library for MQTT protocol as well that we will need later:

npm install mqtt -g

Generate an AsyncAPI sample

Let’s generate a sample AsyncAPI file using the AsyncAPI CLI tool. This tool uses samples in asyncapi/spec/examples.

asyncapi new -n streetlights.yaml
? would you like to start your new file from one of our examples? Yes
? What example would you like to use? Streetlights API Simplified - (protocols: mqtt)
? open in Studio? Yes
Created file streetlights.yaml...
Studio is running at http://localhost:3210?liveServer=3210
Watching changes on file streetlights.yaml

This creates a streetlights.yaml file for a simple event-driven application using MQTT protocol.

You’ll notice that it has an MQTT server:

servers:
  mosquitto:
    url: mqtt://test.mosquitto.org
    protocol: mqtt

It also has a single channel on the server to publish messages to:

channels:
  light/measured:
    publish:
      summary: Inform about environmental lighting conditions for a particular streetlight.
      operationId: onLightMeasured
      message:
        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.

Once the file is generated, the AsyncStudio opens it automatically and you can see it visually:

Validate the AsyncAPI file

AsyncStudio warns you if the AsyncAPI file is not valid but you can also validate it using the AsyncAPI CLI:

asyncapi validate streetlights.yaml
...
✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Generate code from the AsyncAPI file

Once you have a valid AsyncAPI file, you can use AsyncAPI generators to generate code from it.

For example, this generates code using the Node.js template:

asyncapi generate fromTemplate streetlights.yaml @asyncapi/nodejs-template -o streetlights -p server =mosquitto

It generates a Node.js server, in streetlights folder, capable of receiving MQTT messages outlined in the AsyncAPI file.

You can see the list of official generator templates for other languages and frameworks.

Note: I found these generators quite brittle and limited. They work on a subset of use cases covered by AsyncAPI and as soon as you go beyond basics, they do not work or have some limitation. Nevertheless, they can be useful as you start learning about AsyncAPI.

There are other tools like Modelina to generate data models for your AsyncAPI definitions.

Run the code

Start the generated app:

cd streetlights npm install npm start

This starts up the server waiting for MQTT messages:

> streetlights-api-simplified@1.0.0 start
> node src/api/index.js

 SUB  Subscribed to light/measured
Streetlights API Simplified 1.0.0 is ready! 

🔗  MQTT adapter is connected!

In a separate terminal, send a message to the server using the MQTT library you installed earlier:

mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2022-06-07T12:34:32.000Z"}'

You should see that the server received the message:

← light/measured was received:
{ id: 1, lumens: 3, sentAt: '2022-06-07T12:34:32.000Z' }

We generated an AsyncAPI sample, visualized it, validated it, and even generated some starter Node.js code. This is pretty cool!

In the next blog post, I want to show you how to author your own AsyncAPI file for 2 simple microservices and get into more details about publish/subscribe semantics of AsyncAPI, so stay tuned!

Originally published at https://atamel.dev.