oktools

OpenAPI & Swagger Validator

Validate an OpenAPI 3.0, 3.1 or 3.2 specification, or a Swagger 2.0 file, written in YAML or JSON. Every error is listed with its line — missing required fields, undeclared path parameters, broken $ref links, unused schemas and mistyped security schemes — and every endpoint is laid out with its parameters, request body and responses. Paste a spec or open a file; everything runs in your browser and nothing is uploaded.

YAML

Validation report

Not valid OpenAPI 3.1.0: 3 errors to fix

  • Error: Response 201 is missing the required field "description". Every response needs one, even an empty string.

    paths › /pets › post › responses › 201
  • Error: "#/components/schemas/Pets" does not point to anything in this document. Did you mean "Pet"?

    paths › /pets/{petId} › get › responses › 200 › content › application/json › schema › $ref
  • Error: The path parameter {petId} is not declared for DELETE /pets/{petId}. Add a parameter with name: petId, in: path and required: true.

    paths › /pets/{petId} › delete
  • Warning: The schema "Error" is never referenced from the paths, so it appears in no request or response.

    components › schemas › Error

YAML · OpenAPI 3.1.0 · 2 paths, 4 operations

Endpoints

Pet Store 1.2.0

https://api.example.com/v1
  • GET/petsList pets
    operationId
    listPets
    Tags
    pets
    Security
    apiKey
    Parameters
    NameInTypeDescription
    limitqueryinteger How many pets to return, at most
    Responses
    StatusDescriptionBody
    200 A page of pets application/json: array of Pet
  • POST/petsAdd a pet1 error
    operationId
    createPet
    Tags
    pets
    Security
    apiKey
    Request body
    application/json: NewPet
    Responses
    StatusDescriptionBody
    201no descriptionapplication/json: Pet
  • GET/pets/{petId}Find a pet by ID1 error
    operationId
    getPet
    Tags
    pets
    Security
    apiKey
    Parameters
    NameInTypeDescription
    petId*pathinteger (int64) The pet's ID
    Responses
    StatusDescriptionBody
    200 The pet application/json: Pets
    404 No pet has that ID —
  • DELETE/pets/{petId}Remove a pet1 error
    operationId
    deletePet
    Tags
    pets
    Security
    apiKey
    Responses
    StatusDescriptionBody
    204 The pet was removed —

What the OpenAPI validator checks

AreaChecks
Document The openapi or swagger version, written as text; info with its title and version; fields the specification does not define, with the one you probably meant; server URL variables and their defaults.
Paths Paths start with / and carry no query string; every {param} is declared with in: path and required: true; no two paths differ only in parameter names; methods are lower case.
Operations Unique operationIds; at least one response; status codes such as 200, 2XX or default; every response has a description; no request body on GET, HEAD or DELETE.
Parametersname and a valid in; a schema or content; no duplicates; Accept, Content-Type and Authorization headers, which OpenAPI ignores.
Schemas Valid types per version (nullable in 3.0, "null" in 3.1); items on arrays; required as a list of defined properties; bounds that can be met; patterns that compile.
References Every local $ref resolves, to the right kind of component; fields beside a $ref that 3.0 ignores; components nothing uses.
Security Each scheme has the fields its type needs; requirements name defined schemes and scopes; schemes no requirement uses.

How it works

The document is read by its first character: a brace or a bracket means JSON, anything else is YAML, and both go through a YAML document model that records the line every key was written on, which is how an issue can point at line 43. The version field then decides the rules — swagger: "2.0", or openapi: 3.0, 3.1 or 3.2 — and the document is walked object by object against field lists written out from the specification text: which fields are required, what type each must have, which fields an object may carry at all, and, when a name is unknown, the one you probably meant.

References are a second pass. Every local $ref is followed as an RFC 6901 pointer to check that it lands on something, and on the right kind of thing — a parameter where a parameter belongs — with chains of references followed until they end or loop. The same walk records which components can be reached from the paths, so a schema nothing uses can be named, and a discriminator mapping or a reference inside an x- extension counts as a use. Nothing is fetched: a $ref into another file is noted once and otherwise left alone.

A document under 200,000 characters is checked on every keystroke; above that, checking waits for a pause in typing, so a 10 MB spec stays responsive. Issues are sorted errors first and then by line, and the first two hundred are rendered before a Show more button, since a broken generated spec can produce thousands. The endpoints panel is built by a separate reader that follows the same references but never complains, so a half-written spec still lists the operations it does describe, each with the number of errors and warnings found inside it.

Examples

Find a path parameter that was never declared

Every {name} in a path has to be declared with in: path and required: true, on the operation or on the path item, and the message says exactly that. The suggestion beneath it is the third severity: a field the specification leaves optional but readers rely on.

Specification
openapi: 3.0.3
info:
  title: Orders
  version: "1"
servers:
  - url: https://api.example.com
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      responses:
        '200':
          description: The order
Report
OpenAPI 3.0.3 · Orders 1: 1 errors, 0 warnings, 1 suggestions

ERROR (line 9): paths › /orders/{orderId} › get
  The path parameter {orderId} is not declared for GET /orders/{orderId}. Add a parameter with name: orderId, in: path and required: true.

SUGGESTION (line 2): info
  info has no description. A sentence or two on what the API is for helps every reader of the docs.

Quote a version that YAML reads as a number

To a YAML parser openapi: 3.1 and version: 1.0 are the numbers 3.1 and 1, so the file claims to be OpenAPI 3.1 with no patch version and an API version of 1. Both messages give the fix. This is the report as copied with the Errors filter on, which is why the header still counts two suggestions it leaves out.

Specification
openapi: 3.1
info:
  title: Orders
  version: 1.0
paths: {}
Report, errors only
OpenAPI 3.1 · Orders 1: 2 errors, 0 warnings, 2 suggestions

ERROR (line 1): openapi
  openapi must be text, not a number. YAML reads 3.1 as a number; quote the full version: openapi: "3.1.0".

ERROR (line 4): info › version
  "version" must be text, not a number. In YAML, quote it: version: "1".

Fix a $ref with a typo

The reference is looked up in the document and, when nothing is there, its last segment is compared with the names that are, so a mistyped schema name comes back with the one that was meant. This is the sample spec’s broken reference, reported at the line of the $ref itself.

Fragment of the spec
responses:
  '200':
    description: The pet
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Pets'
Issue
"#/components/schemas/Pets" does not point to anything in this document. Did you mean "Pet"?
paths › /pets/{petId} › get › responses › 200 › content › application/json › schema › $ref

Validate a Swagger 2.0 file

A document that opens with swagger: "2.0" is held to the 2.0 rules — host and basePath, a body parameter with a schema, definitions rather than components — and the page reports Valid Swagger 2.0 document with the status line YAML · Swagger 2.0 · 1 path, 1 operation. One suggestion is left.

Specification
swagger: "2.0"
info:
  title: Orders
  version: "1"
host: api.example.com
basePath: /v1
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create an order
      parameters:
        - name: order
          in: body
          description: The order
          schema:
            $ref: '#/definitions/Order'
      responses:
        '201':
          description: Created
definitions:
  Order:
    type: object
    required: [id]
    properties:
      id:
        type: string
Report
Swagger 2.0 · Orders 1: 0 errors, 0 warnings, 1 suggestions

SUGGESTION (line 2): info
  info has no description. A sentence or two on what the API is for helps every reader of the docs.

Supported formats

  • OpenAPI 3.0, 3.1 and 3.2Told apart by the openapi field and each checked against its own field lists: nullable in 3.0 against "null" in a 3.1 type list, webhooks and $defs from 3.1, the query method and additionalOperations from 3.2.
  • Swagger 2.0Documents that start with swagger: "2.0", with host, basePath and schemes, body and formData parameters, definitions and securityDefinitions, held to the 2.0 rules rather than the 3.x ones.
  • YAML or JSON, pasted or openedFiles up to 20 MB, dropped on the editor or chosen with Open file. YAML anchors and merge keys are expanded, a key written twice is a syntax error, and a leading byte-order mark is ignored.
  • Plain-text reportCopy report writes the version, the API title, the three counts and every listed issue with its severity, line and path as text for a pull request comment or a ticket; the severity filter decides which issues it includes.

Use cases

  • Gate a spec change in a pull requestPaste the changed file and copy the report into the review, so a response that lost its description or a schema that was renamed without its references is caught before it reaches the generated client.
  • Read an unfamiliar API before writing codeThe endpoints panel lists every operation with its parameters, body, responses and security, filtered by path, method, tag or operationId, which is faster than scrolling a 5,000-line YAML file.
  • Find out why Swagger UI or a code generator refuses a fileThose tools often stop at a single unhelpful line. The report names each rule the document breaks, in the words of the fix, with the line it is on.
  • Tidy a spec before publishing itThe warnings and suggestions find unused schemas and security schemes, operations without an operationId and parameters without a description, so the published document reads well in every tool.

Limitations

  • References into other files are not followedOnly #/… pointers inside the pasted document are resolved; a $ref to common.yaml or to a URL is noted once. Bundle a multi-file spec first, with redocly bundle or swagger-cli bundle, and validate the result.
  • It checks the document, not the APINo request is sent, so it cannot tell whether a server matches its own spec. Import the spec into the Online API Client to send each operation and have the response compared with the documented schema.
  • Example values are not validatedSchemas are checked for consistency — types, required lists, bounds, patterns — but an example beside a schema is not checked against it. Paste the two into the JSON Schema Validator for that.
  • The rules are the specification’s, not a style guide’sThere is no custom ruleset: naming conventions, a tag on every operation or a house format for error responses are the job of a linter such as Spectral.
  • No rendered documentationThe endpoints panel is a reading view. It does not render Markdown descriptions, show example payloads or offer a try-it-out button.

Frequently asked questions

How do I validate an OpenAPI specification?

Paste the spec into the editor or open the file, in YAML or JSON; the format is recognised from the first character. It is checked as you type, and the report beside it lists every problem with the line it is on — "Line 43" selects that line in the editor, and the line numbers down the side are marked red for errors and amber for warnings. The document is valid once the report has no errors left; warnings and suggestions are worth reading but do not make it invalid.

What is the difference between Swagger and OpenAPI?

Swagger 2.0 is the old name and version of the same specification: it was donated to the Linux Foundation in 2015 and continued as OpenAPI 3.0, while "Swagger" stayed on as the name of SmartBear's tools. A Swagger 2.0 file starts with swagger: "2.0" and keeps its schemas under definitions; an OpenAPI file starts with openapi: 3.x.y and keeps them under components. This validator reads the version field and holds each document to its own rules: Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1 (which aligned schemas with JSON Schema 2020-12) and the 3.2 additions such as the query method.

What are the most common OpenAPI errors?

A response without a description, which the specification requires even when there is nothing to say. A path parameter such as {petId} that is in the URL but never declared with in: path and required: true, or declared on one operation and forgotten on the next. A $ref with a typo that points at nothing — the report suggests the name you probably meant. A version written as openapi: 3.0 or version: 1.0, which YAML reads as a number rather than text. And in OpenAPI 3.0, a description or example written beside a $ref, which tools silently ignore.

What do errors, warnings and suggestions mean?

An error breaks a rule the specification states as a MUST, so tools such as code generators, Swagger UI or an API gateway may refuse the document or misread it. A warning is valid but almost certainly not what was meant: a schema nothing references, a GET request with a body, a security scope the scheme never defines. A suggestion is a field the specification leaves optional but readers and tools rely on, such as an operationId, a summary or a parameter description. You can filter the report to any one of the three.

Does it follow $ref references to other files?

Only references inside the same document, such as #/components/schemas/Pet. Those are followed everywhere — to check that they point at something, that a parameter reference points at a parameter, and to work out which components are never used. A reference into another file or URL is listed once as a note, since the browser has no way to read your other files. To check a spec split across files, bundle it into one first, for example with redocly bundle or swagger-cli bundle.

Can I use it instead of the Swagger Editor?

For checking and reading a spec, yes. The endpoints panel lists every operation with its method, path and summary, and opens to show its parameters with their types, the request body, each response with its media types and schema, and which security schemes apply, with the number of issues found inside it. What it does not do is render interactive documentation or send requests, so there is no "try it out" — it is a validator and inspector, and it never contacts your API.

Is my API specification uploaded anywhere?

No. Parsing, validation and the endpoint list are JavaScript running in your own browser, so the spec you paste or open — with its internal hostnames, paths and examples — is never sent over the network, logged or attached to an analytics event. You can confirm it by opening the network tab and watching it stay empty while you work.