How do I build a single-file Redoc page?

`npx @redocly/cli build-docs openapi.yaml -o redoc.html`. It bundles the spec and the renderer into one self-contained file, which is exactly one publish step.

Why publish docs that will be on a docs site anyway?

Because review happens before the docs site does. A spec change wants eyes on the rendered endpoint — request shape, examples, descriptions — while it is still a pull request, and a diff of YAML is a bad place to review prose.

Do the try-it and search features still work?

Redoc's navigation, search and schema expansion are client-side and run at the link — report HTML executes scripts inside a sandboxed iframe. Interactive request execution is a Redocly paid feature and is unaffected either way.

How does the reviewer's comment reach me?

Threads anchor to the rendered content, so a note sits on the endpoint or the field it is about. If the person editing the spec is an agent, it can read those threads back through MCP and revise.

Can a new build replace the old one at the same link?

Yes — PATCH the same report id. The reviewer's URL keeps showing the current build with the previous ones still available, so a review comment never points at something that has scrolled away.

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

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.

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.

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.
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.
An agent can act on the feedback through MCP if the spec is being edited by Claude Code — see letting 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 →

Swagger UI builds — the other OpenAPI renderer
OpenAPI docs · Share with a client
Publish from CI · MCP

Share Redoc API docs

Publish it

What the URL changes

Limits

Try it

Related