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:
- Sergio's latest specification and parser update
- Maciej's latest design and documentation update
- Missy's latest visual design and experience update
- Alejandra's latest AsyncAPI docs update
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-writeAs 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: numberThe 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 userThe 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 = emailPython 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
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