# Share Redoc API Docs — One HTML File, One Review Link

Canonical: https://commareports.com/share-redoc-api-docs
Published: 2026-09-01

> redocly build-docs bundles an OpenAPI spec into a single HTML file. Publish it to Comma so reviewers comment on the endpoint itself, and each spec change lands as a revision at one URL.

# Share Redoc API docs

An OpenAPI spec is reviewed twice: once as YAML, badly, and once as
rendered documentation, months later, when a consumer discovers the
description was wrong.

The second review is the one that catches things. It just usually happens
after the docs are published, because rendering the spec for a reviewer
means running a server and telling them where.

Redocly's CLI removes half of that — one command, one HTML file.

## Publish it

```bash
npx @redocly/cli build-docs openapi.yaml -o redoc.html

curl -X POST https://commareports.com/api/v1/reports \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html redoc.html \
        --arg title "API docs — $BRANCH" \
        '{title: $title, html: $html}')"
```

Or drag `redoc.html` into [the app](https://commareports.com/).

Navigation, search and schema expansion keep working at the link —
scripts run inside a sandboxed iframe (`allow-scripts`, no
`allow-same-origin`).

For a per-PR preview, `PATCH` a report id stored in your branch's CI
variables, so the same URL shows the current build and every earlier one.
See [GitHub Actions](/ci/github-actions-html-report).

## What the URL changes

- **Review on the endpoint.** "This 409 case is not documented" pinned to
  the operation, not filed as a YAML line number. See
  [commenting on HTML](/comment-on-html).
- **Non-engineers can review.** Support, partner teams, the customer
  integrating against it — none of whom will read the YAML.
- **A revision per spec change.** See
  [revisions and diffs](/share-html-report).
- **An agent can act on the feedback** through [MCP](/docs/mcp) if the
  spec is being edited by Claude Code — see
  [letting an agent respond to comments](/agents/let-an-agent-respond-to-comments).

## Limits

- **HTML body: 5 MB.** A very large spec bundled single-file can exceed
  it; split by tag, or publish per service.
- **Scripts run, sandboxed**: `allow-scripts`, no `allow-same-origin`.
- **60 requests/minute per token.**

## Try it

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

**[Create your first report →](https://commareports.com/)**

### Related

- [Swagger UI builds](/share-swagger-ui-docs) — the other OpenAPI renderer
- [OpenAPI docs](/share-openapi-docs) · [Share with a client](/share-html-file-with-client)
- [Publish from CI](/docs/ci) · [MCP](/docs/mcp)