APIDocsLinter — OpenAPI 3.1 Lint + Breaking-Change Detector
22 findings across an OpenAPI 3.1 spec, 9 lint classes (missing operationId, untyped 5xx, undocumented 429, RFC 7807 gap, breaking parameter rename, deprecated-no-sunset, response schema drift, semver mismatch, PII in query, unsafe-eval). Maps Spectral-style severity to SemVer impact (MAJOR / MINOR / PATCH).
What it is
The shape behind Spectral, Redocly, Stoplight Studio — but pointed at the gap most teams miss: the breaking-change classifier that tells you whether your version bump should be MAJOR, MINOR, or PATCH.
What’s in it
- 22 findings across 9 lint classes:
- missing-operation-id — every operation needs an
operationIdfor codegen - untyped-5xx — schemaless 5xx responses break client parsing
- undocumented-429 — gateway enforces rate-limit but spec doesn’t say so → no retry codegen
- no-rfc7807 — error bodies should use
application/problem+jsonshape - breaking-param-rename —
{orderId}→{id}is a MAJOR break for codegen - deprecated-no-sunset — RFC 8594 requires Sunset header
- response-schema-drift — required-field added = MAJOR break; optional-field added = MINOR
- semver-mismatch —
info.version: 1.4.1with breaking changes inside = wrong bump - missing-example — codegen + docs viewers (Stoplight, ReDoc) cannot render previews
- auth-missing — sensitive admin endpoint without explicit security
- pii-in-query —
?email=leaks in proxy logs, browser history, Sentry breadcrumbs - pagination-missing — list endpoint returning unbounded array
- missing-operation-id — every operation needs an
- SemVer-impact-per-finding: every finding tagged MAJOR / MINOR / PATCH.
- Overall version-bump recommendation at the top — “you said PATCH but you need MAJOR.”
- Copy-pasteable fix per finding — actual YAML/JSON diffs with the before/after.
Why this shape
The gap most API-doc tools leave: they tell you what’s wrong, but not whether shipping it is safe. APIDocsLinter prototypes the breaking-change classifier — every finding tagged with its SemVer impact, the overall version-bump rolled up at the top. The result: you ship 1.5.0 vs 2.0.0 with intent, not by accident.
How it ships
Single HTML file, ~23KB. Zero dependencies. 22 findings × 9 lint classes × SemVer impact in 240 lines of vanilla JavaScript.