OpenAPI Validator & Viewer is a free tool for API descriptions. Paste or open an OpenAPI 3.0, 3.1 or 3.2 document, or a Swagger 2.0 one, in YAML or JSON. It lists every problem in plain words with the line it is on, and shows the API as a readable list of endpoints grouped by tag, with their parameters, request bodies and responses. The document is read in your browser and never uploaded.
How to validate an OpenAPI spec
- Paste the document, or use Open file for a
.yaml,.ymlor.jsonfile. - The badge at the top says whether there are errors. Open Problems to see them, most serious first.
- Choose Show beside a problem to jump to that line in the document.
- Switch to Endpoints to browse the API, and search it by path, method or operationId.
Mistakes it catches
- Path parameters: a
{id}in a path that is never declared, a declared path parameter that is not in the path, or one missingrequired: true. - References: a
$refthat points to nothing, usually a typo in a schema name. - Operations: duplicate
operationIds, which make code generators produce clashing functions, and methods written in capitals such asGET:, which tools silently ignore. - Paths: two paths that differ only in parameter names, such as
/users/{id}and/users/{userId}, which a router cannot tell apart. - Responses, security and servers: invalid status codes, responses without descriptions, undefined security schemes and server variables.
- Schemas: invented types, a required property that is never defined, and features used in the wrong version.
These are checked directly rather than with the official JSON Schema, whose messages rarely say what to fix and which misses several of the rules above. Run against GitHub’s published API description, it finds two required properties that are never defined and a pair of identical paths — the kind of slip a large spec accumulates.
OpenAPI 3.0, 3.1 and 3.2
3.1 aligned schemas with JSON Schema: a value that may be null is written type: [string, "null"], andnullable: true no longer exists. In 3.0 it is the other way round. 3.2 adds the querymethod and additionalOperations. The validator applies the rules of the version your document declares, and says when a feature belongs to another one. A common trap in YAML is version: 1.0, which is read as the number 1; the version must be a quoted string.
Reading the endpoint list
Operations are grouped by their first tag, in the order the document declares its tags. Each one opens to show its parameters (a star marks required ones), the request body’s content types and shape, and each response. Schemas are summarised on one line, such as { id: string, total: number }, following references and noting optional fields with a question mark. To validate example data against one of your schemas, use theJSON Schema Validator; to tidy the YAML itself, theYAML Formatter.
Frequently asked questions
What does it check?
The required fields, every local $ref, path parameters that are undeclared, unused or optional, duplicate operationIds, paths that differ only in parameter names, method names in capitals, response codes, security schemes and server variables, and schema types — including the differences between OpenAPI 3.0, 3.1 and 3.2.
Why is my spec valid in another tool but not here?
Some rules — such as two paths that differ only in their parameter names, or a required property that is never defined — are in the OpenAPI specification but not in its JSON Schema, so schema-only validators miss them. Each message here says what the rule is and why it matters, so you can judge it.
Does it follow $refs to other files?
No. It checks references inside the document and lists any external files it did not follow, because fetching them would mean sending requests from your browser. Bundle the spec into one file first (for example with redocly bundle) to check everything.
Is my API description uploaded?
No. The document is parsed and checked in your browser. That matters for internal APIs whose specs describe systems you would rather not publish.
Why does it flag version: 1.0?
YAML reads 1.0 as a number, so it becomes 1 and the version you meant is lost. info.version must be a string; write it in quotes: version: "1.0".
Last updated