AsyncAPI Generator: turning one AsyncAPI file into code and docs

The specification file goes in, an artifact comes out

AsyncAPI describes the interfaces of event-driven systems, and the generator's job is to stop that description from rotting. Its stated purpose is to let you generate whatever you want based on the AsyncAPI specification file as input, and the project description spells out the range: Markdown documentation, Node.js code, HTML documentation, anything.

The mechanism is template driven. A template takes the parsed document and renders an output, and the same generator can therefore serve a documentation site in one run and a Java JMS application in another. The official template list in the README shows the range in practice, covering Java JMS, Java Spring Cloud Stream, an HTML documentation site and a Markdown file among the templates still in active use.

The audience is a team that has already adopted AsyncAPI as its source of truth for event interfaces. If you are still deciding how to describe your broker topics, the generator has nothing to chew on, and the effort belongs in the specification first.

One Turborepo monorepo, five publishable packages

The repository is a monorepo managed with Turborepo, and the packages inside it are published separately. The README lists five: the Generator itself in apps/generator, Hooks in apps/hooks, the AsyncAPI React SDK in apps/react-sdk, generator helpers in packages/helpers and generator components in packages/components.

The division of labour is sensible. The React SDK is the library that lets templates use React as the render engine, and it understands the components that Generator templates expose. The helpers package supplies utility functions that cut boilerplate and speed up template authoring. The components package holds reusable components that different templates can share, which is the mechanism for avoiding duplicated markup across templates.

Turborepo sits above all of this as the task runner, and the root package.json is a private workspace whose scripts are mostly thin wrappers over turbo. It also defines filtered scripts per package, such as generator:test, components:test, helpers:test, templates:test and hooks:test, so a developer can run the suite for one workspace rather than the whole tree. The consequence for adopters is that the published npm packages are the unit of consumption, not the repository.

Hooks let a template run code at a chosen moment

Hooks are functions the generator calls at specific moments in the generation process, and they exist so template developers can extend what happens around a template run. A hook can be an anonymous function or a named one, and it may take arguments or be expected to return a value.

The README is explicit about one operational detail that catches people out: the hooks are included in the generator without adding any specific dependency to the library, but you still have to enable a given hook in the configuration explicitly, because some hooks can execute automatically without a specific parameter being passed. In other words, the presence of a hook in the template does not make it run, and the configuration file is where that decision is made.

For a team writing its own template, this is the extension point that decides how much a template can do beyond rendering. It also means the security story depends on the template you use: a template can run code during generation, so a template from an unvetted community repository deserves the same scrutiny as a build script.

Baked-in templates ship inside the package, and are experimental

The generator carries its own templates under the packages/templates directory, described as official templates shipped directly inside the Generator package. The README calls them baked-in templates, says they cover code, docs, configs and SDKs, and states that they follow a strict, opinionated structure for consistency and maintenance.

The same paragraph labels the feature experimental and says it is not recommended for production use, pointing to separate documentation for people who want to try it or learn from it. That warning is the deciding fact for an engineering decision. A template that ships with the tool is convenient because there is nothing extra to install or version, but the project itself declines to stand behind it for production use at the time of writing.

There is a second reason to think twice. Templates that live inside the package version are coupled to the generator version, so a generator upgrade can change the output without a separate template upgrade. That is convenient in a monorepo and awkward in a company that pins dependencies carefully and wants generated code to change only when a human decides it should.

Most of the official template list is archived

The template table in the README is the most useful document in the repository for a prospective user, and it marks the templates that are no longer maintained as (archived). Of the thirteen listed templates, nine are marked archived and four are not: the Java JMS application, the Java Spring Cloud Stream service, the HTML documentation site and the Markdown file.

The archived set still covers familiar ground, including Node.js and WebSocket services, Java Spring, Python with Paho, TypeScript and.NET NATS clients, a Go client using Watermill, and PHP and.NET RabbitMQ clients. The README states that archived templates live in the asyncapi-archived-repos organisation and are no longer maintained, and it points at the baked-in templates as supported alternatives, with the community list available separately through a topic search on GitHub.

The honest reading is that the template ecosystem has thinned out. The generator itself is what the AsyncAPI Initiative maintains; the templates are separate repositories with their own lifecycles, and most of them stopped. Anyone planning to standardise on a Java or documentation template should confirm its repository is still receiving work before committing to it.

Building and testing with turbo, npm and Docker

The root package.json is the entry point for development. Its scripts are thin wrappers over turbo, so the same task names apply across packages:

"build": "turbo build",
"dev": "turbo dev",
"test": "turbo run test",
"lint": "turbo lint",
"lint:fix": "turbo run lint:fix"

Filtered variants exist for individual workspaces, including generator:test, generator:test:unit, generator:test:integration and generator:test:cleanup, and the snapshot-update script is generator:update:snapshot, which runs the integration test update target. A developer working on one package can therefore run just that package's suite.

The container path exists too, and the Dockerfile is explicit about how it works. The base image is built on Node 24.11 on Alpine:

ARG NODE_VERSION=24.11
FROM node:${NODE_VERSION}-alpine AS base

WORKDIR /app

The build prunes the monorepo down to the package manifests with turbo before installing, and the dependency install is done with scripts disabled:

RUN npx [email protected] prune @asyncapi/generator @asyncapi/generator-components --docker --out-dir /out
RUN npm ci --ignore-scripts

The compose file ties it together with a single service named test, which builds the local image and runs the test suite, adding the lint step when the LINT variable is set.

Where the generator is the wrong tool

Three cases stand out. The first is a project without an AsyncAPI document. The generator's input is the specification file, and there is no reverse direction, so a team that has not written one gets nothing from installing it.

The second is a case where a one-off script would serve better. If you need a single Markdown file from a single document, hand-writing it or a ten-line script is faster than wiring a template, a render engine and a hook configuration. The generator earns its cost when the same transformation is repeated across many documents and many services, and the template is worth maintaining.

The third is a compliance-sensitive environment that blocks template code execution. Because hooks can run code during generation, a security policy that forbids running unreviewed repository content in the build pipeline conflicts with the template model at its core. The same applies to supply chain review: a template is code you execute, and the list above shows that the set of templates under active maintenance is small, so the review burden lands on a project with one or two people who chose the template.

Apache-2.0, version 3.4.1, and a main branch that moves often

The project is licensed Apache-2.0, with LICENSE and NOTICE files at the repository root. The NOTICE file is the one to read alongside the licence when you redistribute generated output or depend on the packages, since it is where attribution details for included third-party material are recorded. That is a reading task, not legal advice.

On versioning, the packages move independently. The most recent published versions listed are @asyncapi/generator 3.4.1 and @asyncapi/generator-hooks 0.1.2, both dated 2026-09-17, with generator-hooks 0.1.1 a little earlier on 2026-08-07. The hook package is at 0.1.x, which is a fair signal that the hook surface is still settling, and a template that depends on a hook API should expect that API to move.

The repository is not archived and the last push was on 2026-10-16. Development runs on the master branch, with Turborepo tasks, a Jest base config, an.eslintrc setup, a.releaserc configuration and a.changeset directory in the root, which is the standard machinery for a monorepo that publishes several packages from one tree.

Editorial conclusion

Adopt AsyncAPI Generator if your team already writes AsyncAPI documents and wants documentation or service scaffolding generated from them, and pick a template you trust since most of the official ones are archived. Do not adopt it for a project that has no AsyncAPI file yet, since the generator takes the specification as its input, and do not build on the baked-in templates, which the README marks as not recommended for production use. Before you start, read the archived markers on the official template list, check the Apache-2.0 LICENSE and NOTICE files for what you redistribute, and confirm the template you pick is still maintained, because only a handful of the listed templates are.

Frequently asked questions

Official sources

1. asyncapi/generator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases