Introduction

The AsyncAPI generator is a tool that generates anything you want using the AsyncAPI Document and Template that are supplied as inputs to the AsyncAPI CLI. The generator was built with extensibility in mind; you can use the generator to generate anything you want, provided that it can be defined in a template, such as code, diagrams, markdown files, microservices, and applications. A number of community-maintained templates are now available for immediate usage.

Note: If your primary objective is to generate models/classes for your event-driven architecture apps, use AsyncAPI Modelina, which is supported in the AsyncAPI CLI, instead of using the AsyncAPI Generator. Modelina is specifically designed for model generation and provides utilities for working with the AsyncAPI document.

Generator use cases

• Generation of API documentation - Transforms an AsyncAPI document into a human-readable website or Markdown where developers can visualize channels, operations, messages, and payload schemas, instead of reading the raw YAML/JSON definition.
• Generation of APIs' client libraries (SDKs) - Produces ready-to-use code packages for API consumers that abstract away the protocol/networking logic (connecting, subscribing, and publishing over Kafka, WebSocket, MQTT, and more), so developers interact with the API by calling functions rather than writing raw connection code.
• Generation of APIs' boilerplate code - Scaffolds the project skeleton for API providers: server configuration, directory structure, and connection logic, plus stub handler files, so you can skip the setup and focus immediately on business logic.
• And anything else you can template - The use cases above are just the popular ones. Because the output is driven entirely by the template, you can generate whatever your AsyncAPI document can describe: usage examples, test cases, Helm charts, config files, diagrams, and more.

Generator advantages

• Quick to setup and easy to use on a regular basis
• Effortless generation of complex documents
• Number of community maintained AsyncAPI templates

Generation process

1. The Generator receives the Template and AsyncAPI Document as inputs.
2. The Generator sends to the Parser the asyncapiString which is a stringified version of the original AsyncAPI Document.
3. The Parser uses additional plugins such as the OpenAPI, RAML, or Avro schemas to validate custom schemas of message payloads defined in the AsyncAPI Document.
4. If the Parser determines that the original AsyncAPI Document is valid, it manipulates the document and returns a set of helper functions and properties and bundles them together into an asyncapi variable that is an instance of AsyncAPIDocument. The asyncapi helper functions make it easier to access the contents of the AsyncAPI Document.
5. At this point, the Generator passes the asyncapi, the originalAsyncAPI, and the params which collectively make up the Template Context to the Render Engine.
6. AsyncAPI has a Render Engine(react). The Generator passes both the Template Files and the Template Context to the Render Engine.
7. Once the Render Engine receives the Template Files and the Template Context, it injects all the dynamic values in your react based Template Files using the Template Context. As a result, the Render Engine generates markdown, pdf, boilerplate code, and anything else you specified to be generated as output.

You can generate anything you want using the generator as long as it can be defined in a Template.

The diagram below depicts the entire process of passing the Template and AsyncAPI Document to the AsyncAPI generator tool, how the generator uses these inputs to generate the desired output, and example outputs you can get from the render engine.

params are template-specific options passed to the asyncapi generate fromTemplate CLI command to customize the generated output.