How do I share rendered OpenAPI docs without deploying them?

Build a single HTML file — `redocly build-docs openapi.yaml -o api.html` — and POST it to https://commareports.com/api/v1/reports with a Bearer comma_sk_ token. Comma renders it in a sandboxed iframe with scripts enabled, so the Redoc navigation, schema expanders and code samples all work at the URL.

Does Swagger UI work too?

Yes, if you load its assets from an allowlisted CDN. Comma permits scripts and styles from jsdelivr, unpkg, cdnjs and esm.sh inside report HTML, and Swagger UI's dist is published on all of them. Inline the spec into the page rather than fetching it from a URL the sandbox may not reach.

Why review API docs instead of the spec file?

Because reviewers who are not the API author read the rendered page, not the YAML. Inconsistent naming, a missing error response, an example that contradicts the schema — those jump out on the page and hide in a 4,000-line diff.

Can a partner comment on one endpoint?

Yes. They highlight that endpoint's section and pin the note there. The thread stays attached to the endpoint across rebuilds, which is what makes design review on an API converge.

Can it rebuild automatically when the spec changes?

Yes — publish from CI on every merge to the spec, PATCHing one report id so the URL is stable and each build lands as a new revision.

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

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.
Partners can read it without access to your repo. Share the link, keep the spec private. See the sharing model.
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 →

Share OpenAPI docs for review

Publish it

What the URL changes

Limits

Try it

Related