AsyncAPI tooling update - Week 39

Jonas Lagoni Avatar

Jonas Lagoni

·5 min read

This post bundles updates from the following official tools, but not limited to: bundler, chatbot, studio, diff, glee, create-glee-app, cli, optimizer, modelina, generator, generator-react-sdk, java-template, java-spring-cloud-stream-template, java-spring-template, dotnet-nats-template and ts-nats-template.

You can find the last tooling update here.

Finally time for another tooling update after the holidays and catchups!

In case you want to read what other changes have been happening get the overviews here:

Highlights

These are some of the highlights of changes that have happened in the tools or what's to come! It of course does not cover all the changes but only certain ones.

AsyncAPI version 2.5

Yesterday AsyncAPI 2.5 was released, and shortly after most of the tools were updated to support it, some just required a simple update of the parser dependency (thank god for CI), and some required a bit more work to support the new features.

You can take a look at Vladimír Gorej release notes to see the tools and which versions you need to upgrade to.

CLI

The long awaited feature from Souvik to integrate the generator into the CLI has finally arrived! This means you from your favorite CLI tool can trigger code generation from any template.

1USAGE
2  $ asyncapi generate fromTemplate [ASYNCAPI] [TEMPLATE] [-h] [-d <value>] [-i] [--debug] [-n <value>] [-o <value>] [--force-write] [-w] [-p <value>] [--map-base-url <value>]
3
4ARGUMENTS
5  ASYNCAPI  - Local path, url or context-name pointing to AsyncAPI file
6  TEMPLATE  - Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
7
8FLAGS
9  -d, --disable-hook=<value>...  Disable a specific hook type or hooks from a given hook type
10  -h, --help                     Show CLI help.
11  -i, --install                  Installs the template and its dependencies (defaults to false)
12  -n, --no-overwrite=<value>...  Glob or path of the file(s) to skip when regenerating
13  -o, --output=<value>           Directory where to put the generated files (defaults to current directory)
14  -p, --param=<value>...         Additional param to pass to templates
15  -w, --watch                    Watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory.
16  --debug                        Enable more specific errors in the console
17  --force-write                  Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir (defaults to false)
18  --map-base-url=<value>         Maps all schema references from base url to local folder
19
20DESCRIPTION
21  Generates whatever you want using templates compatible with AsyncAPI Generator.
22
23EXAMPLES
24  $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template --param version=1.0.0 singleFile=true --output ./docs --force-write

As you can see it has all the features which the current generator has, so you will not miss anything!

Modelina

Union interpretation

Even though unions have been supported in the core models for some time, inputs such as AsyncAPI, JSON Schema, and OpenAPI documents did not create the appropriate models to be more accurately rendered.

Thankfully Kenneth Aasan came to the rescue and solved the issue. This means that from version 1.0.0-next.10 you should see more accurate union representations.

1asyncapi: '2.5.0'
2info:
3  title: Account Service
4  version: 1.0.0
5  description: This service is in charge of processing user signups
6channels:
7  user/signup:
8    subscribe:
9      message:
10        payload:
11          type: object
12          additionalProperties: false
13          properties:
14            email:
15              oneOf: 
16                - type: string
17                - type: number

The scattered AsyncAPI document (asyncapi.yaml), for whatever reason the email can be either a string or number

1class Root {
2  private _email?: string | number; 
3
4  constructor(input: {
5    email?: string | number,
6  }) {
7    this._email = input.email;
8  }
9
10  get email(): string | number | undefined { return this._email; }
11  set email(email: string | number | undefined) { this._email = email; }
12}

TypeScript example output with union types

If they are supported in the language of course, as many languages dont natively support unions, we still need to figure out how to handle it i.e. for Java, Go, C#. We currently just fall back to the most unconstrained type i.e. allow everything. TBD!

Python

On the backbone of what Mahak started Modelina now finally supports python!

This means you from your AsyncAPI document can get the core data model for Python:

1asyncapi: '2.5.0'
2info:
3  title: Account Service
4  version: 1.0.0
5  description: This service is in charge of processing user signups
6channels:
7  user/signup:
8    subscribe:
9      message:
10        payload:
11          type: object
12          properties:
13            email:
14              type: string
15              format: email
16              description: Email of the user

The AsyncAPI document (asyncapi.yaml)

1class Root: 
2  def __init__(self, input):
3    if hasattr(input, 'email'):
4      self._email = input.email
5  @property
6  def email(self):
7    return self._email
8  @email.setter
9  def email(self, email):
10    self._email = email

Python output for the above AsyncAPI document

Next up is adding presets to properly support the serialization of the data models.

Bundler

If you love decoupling your AsyncAPI documents, you might have reasons to bundle them all together within a single AsyncAPI document at some point. This is what the bundler can help you with, and a feature that's been brewing for some time finally arrived a couple of weeks ago, which enables you to bundle external resources into the components section of the AsyncAPI document. I included it in the last update, where you can read more about the feature.

To that end

In the end, thank you to everyone who contributes to AsyncAPI in any way you can 💜 If you also want to help out but don't know where to begin, then join the #11_how-to-contribute channel on Slack so we can help you any way we can 💪

If you have worked on something or are working on something that you would like to be included in these updates, feel free to reach out on slack!

Photo by Markus Winkler on Unsplash