Home / Features
What it reads, what it checks, and what it will not claim
Built for the person who has to defend a documentation review to a team that disagrees with it.
How it behaves
Evidence on every finding
A finding names the operation, the place in your file it inspected and what it expected to find there. Absences are evidence too: "looked here, found no schema for application/json".
Deterministic
Fixed rules plus small local text checks (vague wording, repeated descriptions, descriptions that only restate a name). The same input always produces the same report, so a re-run after a fix is a fair comparison.
Honest about coverage
Every rule ends in one of six states: gap, no gap, not applicable, could not be assessed, switched off, or failed. A rule that lacks the input it needs is "could not be assessed". It is never a pass and never takes points off.
Grouped by cause
Fifty-three operations with no error responses are one cause with fifty-three places, not fifty-three problems. You fix causes, so the report counts causes.
No overall grade
Each area gets its own sub-score with a coverage label and a trace of every deduction. We do not combine them, because a combined number hides which area is hurting developers and invites argument about the weights.
Says what it measured, and what it did not
Each rule shows how many of its findings people have judged right or wrong, or "not measured". See how we measure.
What it reads
OpenAPI 3.0, 3.1 and Swagger 2.0
JSON or YAML, uploaded or fetched by address. References are followed, and anything it could not read is listed in the report.
Guide sites, including JavaScript-built pages
Give it the address of your developer guide. Pages built by script are read in a real browser that is never allowed to reach the network by itself: every request it makes is answered by the same controlled fetcher or refused.
Folders of Markdown
Documentation in a repository can be reviewed offline. Links are checked inside the folder, and only links that name a file are judged missing.
Several sources, one review
A specification and its guide are read into one picture. Before reporting a gap, a rule asks whether another source already answers it, and lists the answer instead of the gap.
What it hands back
The report
Findings with evidence, impact and recommendation, by area, with coverage. See a sample.
The teardown
A printable one-page summary made only of counts, sums and sorts. See a sample.
The diff
Resolved, still there and new between two reviews. A fix is counted only when its rule ran again over input read in full. See a sample.
SARIF and an evidence manifest
The same findings in the format code-scanning tools read, and a manifest of which rules ran at which version over which input.
Where it can run
Command line, library and REST API
Use it in a pipeline, call it from your own tools, or use the web interface that sits on the same API.
On your own machine
It runs on one host with Docker Compose. Your documentation does not have to leave your network.
Safe fetching by default
It fetches public addresses only, checks every redirect, honours robots.txt and limits size and time. Private and internal addresses are refused.
Rule profiles you can read
Rules and their settings are a plain JSON profile checked against a published schema, so switching a rule off is a visible decision.
What it does not do yet
It does not call your live API, watch your documentation over time, comment on pull requests or block a merge, and it has no accounts or sign-in. It does not judge whether a description is true, only whether it exists, agrees with the rest and checks out against the file. We would rather say so here than have you find out later.
All 41 rules
Grouped by area. Each rule's measurement status is on How we measure.
Contract (16)
Internal $ref that does not resolve
CC-REF-01Operation has neither summary nor description
CC-DESC-01Required parameter or required request property has no description
CC-PARAM-01Response has no description
CC-RESP-01Operation documents no error response
CC-ERR-01The API description and a guide state different maximums for the same parameter
CC-CONFLICT-01Path placeholder has no path parameter definition
CC-PATH-01Request or response declares a structured content type but no schema
CC-SCHEMA-01Path or query parameter has no type information
CC-TYPE-01The same property has incompatible types in different schemas
CC-CONSIST-01Server description and address point to different environments
CC-ENV-01Operation requires a security scheme that is not defined
CC-SEC-01Inconsistent casing of paths or query parameters, or verbs in some paths
NAME-01Description is a placeholder, only repeats the name, or is too short to help
CC-DESC-02Description uses vague wording (etc., various, as needed)
CC-DESC-03Several operations share the same description
CC-DESC-04
Onboarding (5)
Where credentials come from is not described
AUTH-03OAuth2 scopes are not described or not tied to operations
AUTH-04No usable authentication described
AUTH-01Security scheme has no description
AUTH-02Code sample uses a placeholder that no text explains
ON-ENV-01
Errors (3)
Error response example does not validate against its own schema
ERR-05Which failures are worth retrying is not described
ERR-04Error responses lack a shared, machine-readable shape
ERR-02
Webhooks (3)
Webhook or callback has no payload schema
WH-01Webhook signature verification is not described
WH-02Webhook delivery retries and acknowledgement are not described
WH-03
Examples (2)
Operation with a body has no example request or response
CC-EX-01Request or success-response example does not validate against its own schema
CC-EX-02
Limits (2)
429 is documented without telling clients when to retry
RATE-02API documents no rate limiting
RATE-01
Reliability (2)
Idempotency key lifetime and reuse are not described
IDEM-02Resource-creating POST has no idempotency key
IDEM-01
Data (2)
Date/time property has no format or timezone information
DATA-02Date/time example has no timezone although the contract says it has one
DATA-03
Pagination (2)
List operation does not document how to page through results
PAG-01List operations use different pagination styles
PAG-02
Workflow (1)
202 Accepted response does not say how to learn the outcome
WF-04
Lifecycle (1)
Deprecated operation does not say what to use instead
CC-DEP-01
Links (1)
In-scope documentation link returns 404/410, points to a missing anchor, or names a file that is not in the supplied documents
LINK-01
Documentation (1)
A JSON code sample is not valid JSON
DOC-CODE-01
See what it finds in your API
Send us your OpenAPI file or the address of your docs. We run the review and send you the report.