Does Spectral write HTML directly?

Yes. `spectral lint --format html --output spectral.html` produces a standalone page — no conversion step. Spectral also supports json, junit, sarif, stylish, text, teamcity, pretty, github-actions, code-climate and gitlab.

What does a Spectral report contain?

Every rule violation against your ruleset, with the JSON path into the spec, the severity, and the rule that fired — which is what makes it arguable, and therefore worth commenting on.

Can I lint AsyncAPI too?

Yes. Spectral ships rulesets for OpenAPI and AsyncAPI, and the output format is identical, so the publishing flow does not change.

Should Spectral fail the build?

Use `--fail-severity=error` on a separate gate step and keep the reporting step muted with `|| true`, so warnings publish without breaking the pipeline.

Why publish a style-guide run?

Because API style is a negotiation. A URL with anchored threads lets the rule and the objection sit in the same place, instead of the rule living in a repo and the objection in a chat channel.

Share a Spectral report

An API style guide is a policy document that nobody reads until it blocks them. Spectral turns it into findings, which is a big improvement — and then prints those findings into a CI log, which is not.

Unlike most linters, Spectral will hand you a page directly.

One command, one page

npm i -D @stoplight/spectral-cli

npx spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  --format html \
  --output spectral.html || true

No converter, no SARIF hop. --format html is built in.

Publish it

Drag spectral.html into the app, or from CI:

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 spectral.html \
        --arg title "API style — $GITHUB_REF_NAME" '{title: $title, html: $html}')"

Keep a separate spectral lint --fail-severity=error step if you want the gate; the reporting step should publish warnings too.

Style rules are a negotiation

This is the report type where commenting earns its keep. Every Spectral finding is one of two things: a spec that should change, or a rule that should. Both are arguments, and arguments need a shared surface.

Anchored threads on the violation — "operationId casing: we inherited snake_case from the old gateway, exempting v1" — so the exemption lives next to the finding rather than as a spectral.yaml override with no context. See commenting on HTML.
Revisions, so a ruleset tightening is a diff, and the spec owner can see what a new rule would have flagged before it is enforced.
Access per report — public if the spec is public, team-scoped if it isn't. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total.
60 requests/minute per token.

Try it

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

Publish an API report →