Comma

Share Scalar API docs

An API reference is the one document where a wrong line has a support ticket attached to it. Which is why it should be reviewed by the people who implement the endpoints — and why the reference usually reaches them as a link to a spec file on a branch.

Render the reference to one file

<!-- scalar.html -->
<!doctype html>
<html>
  <body>
    <script id="api-reference" type="application/json">
      <!-- your OpenAPI document, inlined -->
    </script>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  </body>
</html>

Inline the spec into the <script type="application/json"> block rather than pointing Scalar at a URL. A reference page that fetches its own spec is a page that renders empty for anyone outside your network — the self-contained HTML rule applies here as much as to a chart.

Generate it in the job that already validates the spec:

jq -c . openapi.json > /tmp/spec.json
python - <<'PY' > scalar.html
import json, pathlib
spec = pathlib.Path("/tmp/spec.json").read_text()
tpl = pathlib.Path("scalar.template.html").read_text()
print(tpl.replace("<!-- SPEC -->", spec))
PY

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html scalar.html \
        --arg title "API reference — $GIT_SHA" '{title: $title, html: $html}')"

Why review beats "read the spec"

  • Anchored threads — "this field is required in practice" sits on the endpoint. See commenting on HTML.
  • Revisions at one URL — one report id for the reference; each spec change appends a revision, so a reviewer can see what moved.
  • Access per report — unlisted for a partner, domain-gated for a customer's org, team-only pre-launch. See the sharing model.

Limits

  • Entry HTML: 5 MB. A large inlined spec plus the renderer can approach it; split by tag, or attach the spec as an asset and accept the fetch.
  • Assets: 25 MB per file, 250 MB and 500 files per report.
  • 60 requests/minute per token.

Try it

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

Publish an API reference →

Related