Align Production Reality and Event Documentation with the AsyncAPI Discovery Tool

The idealized world of AsyncAPI is neat and tidy:

• Interface definitions show developers exactly what events are exchanged amongst producers and consumers.
• Event contracts only change when permitted by well-defined governance processes.
• Bindings fill in the implementation details for open-source brokers like Kafka (including Confluent) and RabbitMQ along with closed-source brokers like IBM MQ and Solace.

The real world is often messier. In the decades-long absence of an asynchronous API spec, teams adopted (or didn’t adopt, or chose to ignore) different API definitions and governance. The result is a twisted mess of event producers, consumers, data paths, and multiple broker technologies, from on-premises to cloud connections.

Oftentimes, removing an event topic or queue requires nerves of steel, for fear it might disrupt key functionality. Many a middleware engineer has found religion during a production broker clean-up.

Thankfully, the AsyncAPI Discovery Tool offers a better way.

Event Discovery Agentby SolaceLabsDiscover event broker configuration, scan a schema registry, and optionally attach a passive listener to a broker to scan events as they flow and then present the discovered data in AsyncAPI format.Open on GitHub

How the AsyncAPI Discovery Tool Works

The AsyncAPI Discovery Tool analyzes event traffic passing through brokers like Kafka, RabbitMQ, IBM MQ, Solace, and more. After learning how the broker distributes events, the AsyncAPI Discovery Tool generates a corresponding AsyncAPI specification. The generated spec can be used for code generation, documentation, visualization, infrastructure deployment, and more.

AsyncAPI vs. OpenAPIAnswers to common questions about AsyncAPI vs OpenAPI, including what APIs are, how they began, and what the future holds for API spec.Read more

It’s a great starting point for getting events catalogued and governed.

It’s not perfect (more on that later), and there’s a lot more work to be done, but the AsyncAPI Discovery Tool helps your enterprise align production reality with AsyncAPI documentation. And perhaps relieve some tension for middleware engineers.

My colleague Greg Muldrum explained and demonstrated how it works AsyncAPI Discovery Tool works as part of an update our developer relations team did. If you’ve read this far, I’d say it’s safe to say you’ll get a lot out of it!

Getting Started with AsyncAPI Discovery

Getting started means a trip to the SolaceLabs GitHub, where you can find detailed instructions and documentation. (While Solace created AsyncAPI Discovery, it’s open source with an Apache 2.0 license.)

The AsyncAPI Discovery Tool runs as a stand-alone Java Jar, so getting it running requires only Java and Maven. Once it’s up and running, AsyncAPI has its own self-contained UI, offering fill-in-the-blanks configuration (get more details about the UI). Here’s an example for Kafka:

Figure 1: UI for AsyncAPI Discovery for Kafka

Just fill in the configuration, asking your friendly local administrator for help if needed, and then click the “Start Scan” button. After grinding away, the AsyncAPI Discovery Tool returns a consolidated spec file. The AsyncAPI file describes the channels and schemas of events passing through the broker. From there, the world is your oyster: generate code, create infrastructure, or start governing your events.

Figure 2: Resulting (greatly simplified) AsyncAPI spec

Alternatively, power users or those looking to integrate AsyncAPI with other tools should also know that there is a REST API available. This can serve as a great way to audit your infrastructure to detect unauthorized changes, or to confirm that deployments went according to plan.

The Future of the AsyncAPI Discovery Tool

The most obvious place to improve the AsyncAPI Discovery Tool is to expand the number of supported brokers. Right now, it supports:

• Apache Kafka
• Solace PubSub+
• NATS
• RabbitMQ
• HiveMQ

Fortunately, it was built with extensibility in mind. There is a documented plug-in architecture just itching to have more brokers added. If you’re interested, The people who maintain the tool welcome pull requests.

Additionally, it also runs into some of the same issues that confront AsyncAPI more generally, like:

• The confusing publish and subscribe verbs in the output.
• The requirement that a single file must represent a single application makes it tough to get a high-level understanding of the architecture.

As the spec matures, the tooling will hopefully be close behind.

Conclusion

In the meantime, the AsyncAPI Discovery Tool can be a huge help to enterprises that are new to AsyncAPI but experienced with event-driven architecture and messaging. The AsyncAPI Discovery Tool can start you down the road from a tangled event mess, to a well-organized, fully documented, tightly governed architecture.