# Share AsyncAPI Docs — Event Contracts as a Reviewable Link

Canonical: https://commareports.com/share-asyncapi-docs
Published: 2026-09-15

> The AsyncAPI generator writes a static HTML site from your spec. Publish it to Comma so producers and consumers can argue about the event schema on the rendered page.

# 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

```bash
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 `$ref`s, and the server bindings.

## Publish it

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

```bash
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](/comment-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](/docs/sharing).

Pair it with a [Spectral report](/share-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 →](https://commareports.com/)**

### Related

- [Share OpenAPI docs](/share-openapi-docs) · [Share Redoc API docs](/share-redoc-api-docs)
- [Share Scalar API docs](/share-scalar-api-docs) · [Share a Spectral report](/share-spectral-report)
- [Share a Schemathesis report](/share-schemathesis-report) · [Publish from CI](/docs/ci)