Demonstrating some of the first tools to support AsyncAPI v3, and how they can help accelerate your event-driven projects.
AsyncAPI version 3 was released in December 2023. In this post, I want to highlight some of the adoption of this new version of the specification, by sharing some of the things that you can do with AsyncAPI v3 documents. I'll demonstrate this with:
- Event Endpoint Management
Download AsyncAPI documents for Kafka topics shared for reuse
AsyncAPI v3 support added in version 11.1.1 (Dec 2023)
- AsyncAPI java-template
Generate complete Java projects from AsyncAPI documents
AsyncAPI v3 support added in version 0.3.0 (Mar 2024)
- Microcks
Generate Kafka topics with mock data from AsyncAPI documents
AsyncAPI v3 support added in version 1.9.0 (Mar 2024)
Event Endpoint Management
When you have Kafka topics that you want to enable teams to reuse, Event Endpoint Management lets you treat them as asynchronous APIs that can be published and managed. They are then available for developers to discover in an AsyncAPI catalog.
Each topic is documented in the Catalog site, with all of the information from the AsyncAPI document rendered together with sample messages and helpful code snippets.
To use the AsyncAPI document with other tools, you can click on Export AsyncAPI.
A few different versions are available, so if you’re using a tool that doesn’t support AsyncAPI v3 yet, you can choose to download the topic information in one of the AsyncAPI 2.x formats.
For this demo, I downloaded the topic info as an AsyncAPI 3.0 document.
The AsyncAPI document has all the information that you need to start consuming events from the topic, except for a username and password.
To generate custom credentials, specific to your new application, you just need to click on the Generate access credentials button.
Once you have this, you’ve got enough to create an application to consume events from this topic.
AsyncAPI v3 provided all of the documentation needed to use a new Kafka topic, in a portable, open standard way.
java-template
When you have an AsyncAPI document that describes a Kafka topic, java-template can generate you a working skeleton Java project to help you get started with it quickly.
ag your-asyncapi-document.yaml \
@asyncapi/java-template \
-o location-for-your-generated-code \
-p user=username \
-p password=password \
-p server=server-name \
-p package=package.name.for.generated.app
Run this command, and you’ll get a complete Java project. Messages consumed from the topic are deserialized, ready for you to add the logic for what you want your app to do.
For this demo, I’ll just print some of the event properties to the terminal to show that the skeleton app has helpfully deserialized the message contents for me.
That one line was the only change I needed to make for this demo.
The skeleton project includes a Maven setup, so you can build it with mvn package, and then it’s ready to run.
AsyncAPI v3 makes it easy to bootstrap a new project in seconds, by generating working custom code projects, tailored to the topic and events described in the doc.
Microcks
Maybe the Kafka topic has sensitive data on it, and you don’t want developers to create their app using real production data. Microcks can let you generate mock data from the spec, making it easy to create topics for development or test use, using the same AsyncAPI spec to create events that are consistent with the real topic.
New API definitions can be uploaded from AsyncAPI v3 documents.
For this demo, I reused the AsyncAPI document downloaded from the Event Endpoint Management catalog earlier.
This gave me a development version of my orders topic in Microcks.
It created a real Kafka topic on a real Kafka cluster, and started producing mock events to it every three seconds.
To do this, it reused the example message payload in the AsyncAPI document – producing a copy of that message every three seconds.
For development use, randomly generated data would likely be more useful, so I edited the AsyncAPI document to replace some of the values in the example payload with template functions.
After importing the modified AsyncAPI document again, I now had something a little more useful – with some randomly generated values in each event.
AsyncAPI v3 supports development for new projects by letting you quickly generate streams of events for development or test purposes.