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.