OpenAPI Linter
Checks an OpenAPI document for missing responses, unused schemas, references that point at nothing and the other faults that break code generators.
Checks an OpenAPI 3.0 or 3.1 document for the things that break code generators, make client libraries lie, or the specification simply requires. The rules are hand-written and listed on the page — problems, not style preferences.
OpenAPI document
Drop an openapi.yaml
Read in this tab only.
24 findings
errorschema-array-itemscomponents.schemas.Order.items
`type: array` with no `items`.
errorpath-param-undeclaredGET /orders/{orderId}
`{orderId}` in the path is not declared as a parameter.
errorresponse-descriptionGET /orders/{orderId}
The `200` response has no description.
errorschema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` with no `items`.
errorinfo-missinginfo
There is no `info.version`. It is the version of the API, not of OpenAPI.
erroroperation-id-duplicatePOST /orders/{orderId}
The operationId `getOrder` is also on GET /orders/{orderId}.
errorpath-param-requiredPOST /orders/{orderId}
The `in: path` parameter `id` has no `required: true`.
errorpath-param-undeclaredPOST /orders/{orderId}
`{orderId}` in the path is not declared as a parameter.
errorpath-param-unusedPOST /orders/{orderId}
The `in: path` parameter `id` does not appear in the path.
warningpath-trailing-slash/orders/
This path ends with `/`.
warningschema-unusedcomponents.schemas.Customer
Nothing references this schema.
warningoperation-id-missingGET /orders/
There is no operationId.
warningresponse-errorGET /orders/
There is no 4xx response.
warningdescription-missingGET /orders/{orderId}
There is neither a summary nor a description.
warningresponse-errorGET /orders/{orderId}
There is no 4xx response.
warningdescription-missingPOST /orders/{orderId}
There is neither a summary nor a description.
warningresponse-errorPOST /orders/{orderId}
There is no 4xx response.
warningresponse-successPOST /orders/{orderId}
There is no 2xx or 3xx response.
notetag-missingGET /orders/
There is no tag.
notetag-missingGET /orders/{orderId}
There is no tag.
noteparameter-descriptionPOST /orders/{orderId}
The parameter `id` has no description.
noteresponse-default-onlyPOST /orders/{orderId}
The only response is `default`.
notetag-missingPOST /orders/{orderId}
There is no tag.
noteservers-missingservers
There is no server listed, so the base URL is `/`.
OpenAPI
3.0.3
Operations
3
Errors
9
Warnings
9
Notes
6
A hand-written rule set. It catches what makes a code generator stumble, what makes a client library lie, and what the specification actually requires — problems, not preferences. It does not load Spectral rulesets.
To see what changed between two versions, use OpenAPI change diff.
How to use it
Paste the document
JSON or YAML, 3.0 or 3.1. It is parsed in this tab; nothing is uploaded.
Work through the errors first
Each finding carries the rule id and the exact location in the document. Errors are things that will actually go wrong; warnings are things that usually will.
Read the rule list when a finding surprises you
Every rule is written out with its severity and why it exists, so a finding you disagree with is at least an argument you can read.
Common questions
Can it load my Spectral ruleset?
No. This is a fixed, hand-written rule set, chosen for problems rather than for house style. If you have a Spectral configuration, Spectral is the tool that will honour it.
It will not read my Swagger 2.0 file.
Correct — 2.0 is a different document shape, not a slightly older 3.0, and half the rules would not apply to it. Convert it first; `swagger2openapi` is the usual route.
It did not follow my external `$ref`.
A `$ref` inside the document is resolved; one pointing at another file would mean fetching from a path only your machine has. It is reported as a note so you know the check was incomplete rather than clean.
Why is a missing `operationId` a warning?
Because generators use it to name the function they emit for that operation. Without one you get a name derived from the path and method, which changes the moment the path does — a rename in your API becomes a rename in every client.
Feed it from
JSON to JSON Schema
Infers a JSON Schema from one or several samples, unioning the shapes it sees.
JSON Schema Validator
Validates a document against a JSON Schema and reports each failure with its instance path.
curl to Code
Converts a curl command into fetch, axios, Python requests, Go, PHP or PowerShell.
OpenAPI Diff
Compares two OpenAPI documents and separates breaking changes from additive ones.
Next
These accept what this tool produces, so the result can go straight in.
curl to Code
Converts a curl command into fetch, axios, Python requests, Go, PHP or PowerShell.
JSON Schema Validator
Validates a document against a JSON Schema and reports each failure with its instance path.
OpenAPI Diff
Compares two OpenAPI documents and separates breaking changes from additive ones.
YAML Formatter & Validator
Re-indents YAML consistently, validates it, and flags the tab and anchor mistakes that break parsers.
JSON ⇄ CSV
Flattens nested JSON into columns or rebuilds objects from a table, with a dot-path column naming rule.
JSON Diff
Compares two JSON documents structurally, ignoring key order and reporting added, removed and changed paths.