Skip to content

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.

🔒 Runs entirely in your browseropenapilintapiquality

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.

Takes OpenAPI 3.0 and 3.1 documents as JSON or YAML. Swagger 2.0 has to be upgraded to 3 first. A `$ref` within the document is followed; one pointing at another file cannot be checked and is reported as a note.

To see what changed between two versions, use OpenAPI change diff.

How to use it

  1. Paste the document

    JSON or YAML, 3.0 or 3.1. It is parsed in this tab; nothing is uploaded.

  2. 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.

  3. 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

Next

These accept what this tool produces, so the result can go straight in.