How do I generate HTML from an AsyncAPI spec?

`asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o docs` writes a static site with the channels, messages, payload schemas and server bindings.

Why not just share the YAML?

Because the YAML is the contract and the rendered page is the explanation. A consumer team reading a payload schema wants the expanded, resolved view, not `$ref` chasing.

Does the generated site work from the filesystem?

Partly, and unreliably — the bundled JS and the collapsible schema views expect to be served. Publishing it gives everyone the same rendering.

Can I preview a spec change before merging?

Yes. Generate in CI and PATCH one report id per branch; the reviewer opens a working reference for the proposed contract rather than a diff of YAML.

Can consumers comment on a specific message?

Yes. Threads anchor to the rendered content, so 'we depend on this field being non-null' lands on the field, in front of the team about to make it optional.

Share AsyncAPI docs

An event-driven contract has an asymmetry that a REST contract mostly avoids: the producer changes it, and the consumers find out afterwards. A field goes optional, a channel gets renamed, a payload grows a discriminator — and the people who need to object are on other teams, reading a YAML diff in a repo they do not watch.

The generated HTML is the version they will actually read.

Generate the site

npm i -g @asyncapi/cli

asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template \
  -o docs --force-write

That writes a static site: channels, operations, message payloads with resolved $refs, and the server bindings.

Publish it

Drag docs/ (or a zip of it) into the app: index.html becomes the report body, and the bundled CSS and JS upload as assets with their references rewritten. From CI:

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html docs/index.html \
        --arg title "Events — $GITHUB_HEAD_REF" '{title: $title, html: $html}')"

One report id per branch and every proposed contract change has a readable preview before it merges.

The consumer objection needs somewhere to go

This is the report type where anchored comments do real work, because the conversation is across team boundaries and the objection is always specific:

Anchored threads on the message field — "billing reads this as required; making it optional breaks our reconciliation job." On the field, in front of the person about to change it. See commenting on HTML.
Revisions, so a consumer can see what the contract said when they integrated against it.
Access per report — public if the spec is public, team-scoped if the event bus is internal. See the sharing model.

Pair it with a Spectral report: Spectral says the spec violates the style guide, this says what the spec means.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A spec with hundreds of channels produces a large page — split by domain if it approaches the entry cap.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish an API reference →