# Share OpenAPI Docs — Redoc or Swagger UI on a Reviewable Link

Canonical: https://commareports.com/share-openapi-docs
Published: 2026-08-23

> Build your OpenAPI spec into a single HTML file with Redocly, publish it to Comma, and get a URL where reviewers comment on the endpoint they disagree with — before the API ships.

# Share OpenAPI docs for review

An OpenAPI spec has two audiences and they do not read the same artifact. You
review the YAML. Everyone whose opinion you actually need — the client
engineer, the partner integrating next quarter, the support lead who will
answer questions about it — reads the rendered page, if they can get to it.

Most teams cannot get them to it easily. The rendered docs live behind a
deploy, so review happens on the spec diff, and the naming inconsistency that
would have been obvious on the page ships instead.

## Publish it

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

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

`build-docs` inlines the spec into one self-contained page, which is exactly
the shape Comma wants: one file, no sibling directory, no server. Scripts run
inside the sandbox, so the sidebar, the schema expanders and the sample
requests behave as they do locally.

Swagger UI works on the same terms — pull `swagger-ui-dist` from jsdelivr or
unpkg (both allowlisted for report HTML) and embed the spec as a JavaScript
object rather than a `url:` the sandbox has to fetch.

## What the URL changes

- **Design review happens on the endpoint.** Highlight `POST /refunds`, pin
  "this should be idempotent — where's the key?", and the thread stays there.
  See [commenting on HTML](/comment-on-html).
- **Partners can read it without access to your repo.** Share the link, keep
  the spec private. See the [sharing model](/docs/sharing).
- **Every build is a revision.** PATCH one report id from CI and the diff
  between two revisions is a readable changelog of the API surface.

## Limits

- **HTML body: 5 MB.** A very large spec with every example inlined can push
  past it — split by service, one report per API.
- **Scripts run, sandboxed:** `allow-scripts`, no `allow-same-origin`. "Try
  it" panels that call your live API from the browser will be blocked by CORS
  unless your API allows the null origin — treat the published docs as
  reference, not a client.
- **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 Sphinx docs](/share-sphinx-docs) — multi-page builds
- [Comma API reference](/docs/api) · [Publish from CI](/docs/ci)
- [Comment on HTML](/comment-on-html) · [Embed a report](/embed-html-report)