Beautiful HTML reports for your API governance.

Spectral Reporter is a post-processor that turns Stoplight Spectral lint output into a rich, self-contained HTML report you can attach to any CI run — in the spirit of Danny Dainton’s newman-reporter-htmlextra for Newman. Pipe in Spectral’s JSON, get a shareable governance report out. No backend, no accounts, renders offline.

Try the live demo ↓ Install & usage

spectral lint -f json openapi.yaml | npx @api-common/spectral-reporter -o report.html

Severity at a glance

Pass/fail governance banner plus Errors / Warnings / Info / Hints stat tiles with reserved, always-labelled status colors.

Group & filter

Regroup findings by rule, file, or severity; search across every message; toggle severities. All client-side, in one file.

Top offenders

Mini bar-rankings surface the rules and files generating the most findings, so you know where to start.

CI-ready artifact

One self-contained HTML file — no external/CDN requests — perfect to upload from a GitHub Actions or GitLab CI job.

SARIF for code scanning

Emit SARIF 2.1.0 with --sarif and upload governance findings to GitHub code scanning — inline on every PR.

Trends over time

Feed multiple dated runs and get a scoreboard: total findings over time, per-severity trend, and which rules got better or worse.

Report progress, not just deficits

Supply a small per-rule totals sidecar and the report shows compliance — “82% of operations carry a unique id” — beside the violations.

Live demo

Paste the output of spectral lint -f json <your-api> below, or load the bundled sample, then generate the exact report the CLI produces — all in your browser.

Dark

Preview

Install & usage

Run it now (no install)

# From a Spectral JSON file
npx @api-common/spectral-reporter spectral-results.json -o governance-report.html

# Or pipe straight from Spectral
spectral lint -f json openapi.yaml | npx @api-common/spectral-reporter -o report.html

Install as a dev dependency

npm install --save-dev @api-common/spectral-reporter

Flags

-o, --output <file> — output path (HTML report, trend report, or SARIF)
--sarif <file> — also write SARIF 2.1.0 for GitHub code scanning
--format <html|sarif> — sarif writes SARIF to -o / default
--history <dir> — render a trend report across dated JSON runs
--trends — force trend mode (auto when multiple inputs given)
--totals <file> — positive-rule sidecar → adds a compliance scoreboard
--title <text> — report title
--dark — force the dark theme
--open — best-effort open the report in your browser

Trend report across runs

# A directory of dated JSON runs (e.g. 2026-Q1.json, 2026-Q2.json …)
npx @api-common/spectral-reporter --history runs/ -o trend-report.html

# …or pass the run files positionally (oldest → newest)
npx @api-common/spectral-reporter q1.json q2.json q3.json -o trend-report.html

Compliance (report progress, not just deficits)

# totals.json: { "rules": { "operation-operationId": { "checked": 42, "passed": 34 } } }
npx @api-common/spectral-reporter results.json --totals totals.json -o report.html

In GitHub Actions

- name: Lint & report
  run: |
    npx @stoplight/spectral-cli lint -f json openapi.yaml > spectral.json || true
    npx @api-common/spectral-reporter spectral.json -o governance-report.html
- uses: actions/upload-artifact@v4
  with:
    name: api-governance-report
    path: governance-report.html

Upload findings to GitHub code scanning (SARIF)

- name: Spectral → SARIF
  run: |
    npx @stoplight/spectral-cli lint -f json openapi.yaml > spectral.json || true
    npx @api-common/spectral-reporter spectral.json --sarif results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

The HTML rendering is a pure, dependency-free function shared verbatim between the CLI and this page — so the report you download here is byte-for-byte what CI produces. Free and open under the Apache-2.0 license. When you want experts in the loop, .