Skip to main content
Bethemesh
Development

OpenAPI and Swagger validator

Check an API description in JSON or YAML without uploading it.

Paste or import a self-contained JSON/YAML document, then validate it. The report lists errors and explains the scope of the checks.

Was this tool useful?

How does this tool work?

An OpenAPI description acts as a contract between the people developing, documenting and consuming an API. Incorrect YAML indentation, a missing required field or an unresolved reference can prevent it from being used. This validator helps locate those errors in JSON or YAML directly in your browser. It supports Swagger 2.0, OpenAPI 3.0.0–3.0.4 and OpenAPI 3.1.0–3.1.2, within the scope shown in the report.

Checking starts with syntax: the text must parse as a single JSON or YAML document without duplicate keys. The validator then checks the version and expected structure, including API information and the operations described. A syntactically correct file can therefore still fail the OpenAPI schema for its version.

Internal references use JSON Pointers, such as #/components/responses/Ok, to identify locations in the same document. The validator checks their resolution and distinguishes genuine references from $ref keys inside example data. References to other files or remote schemas are rejected; no resolver downloads them.

Additional checks cover operationIds on routes and webhooks, path parameters, and the types of 3.1 schema keywords. A successful result remains partial: it does not check all semantic constraints, formats or example validity. Custom dialects, $id, anchors and dynamic references are reported as outside the supported scope.

A diagnostic path such as /paths/~1health/get/responses identifies the responses field of GET /health: in a JSON Pointer, ~1 represents a slash. A source line is shown when it can be located. Start with the first clear cause before tackling secondary diagnostics from the same incomplete object.

How to use this tool

  1. Provide the document

    Paste the description or import a JSON, YAML or YML file. Bundle references spread across files beforehand.

  2. Run the checks

    Click Validate. Processing stays in your browser and stops after at most ten seconds.

  3. Fix the reported paths

    Start with syntax errors, then correct the reported fields and validate again.

Use cases

Review an API contract

Check a file before committing it or handing it to another developer for integration.

Diagnose an export

Locate structural errors in a description generated by a framework or another tool.

Inspect a private API

Examine an internal description without uploading its contents or calling its endpoints.

Examples

A self-contained document with an internal reference

Paste this complete document to describe GET /health. The 200 response reuses the Ok component from the same file. This checks a document contract; no GET request is sent to a server.

Input

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        "200":
          $ref: "#/components/responses/Ok"
components:
  responses:
    Ok:
      description: OK

Result

Valid within the checked scope
Declared HTTP operations: 1

A missing required field

This YAML can be parsed, but info.version is missing. Add, for example, version: 1.0.0 inside info. An empty paths object is not itself the cause of this error. The reported line depends on where the field appears in your file.

Input

openapi: 3.1.0
info:
  title: Health API
paths: {}

Result

Description needs correction
Path: /info
Structure does not match the specification.
Detail: required: version

An unresolved internal reference

The document still contains the Ok component, but the response requests Absent. Fix the reference name. If you replace it with an external URL, the diagnostic changes to a rejected external reference and no remote file is loaded.

Input

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        "200":
          $ref: "#/components/responses/Absent"
components:
  responses:
    Ok:
      description: OK

Result

Description needs correction
Path: /paths/~1health/get/responses/200/$ref
Internal reference not found.

Tips and best practices

  • info.version is the version of your API; openapi identifies the description format version. They are not interchangeable.
  • A /users/{id} path must declare the id parameter on the path or operation. A query parameter named id does not replace a path parameter.
  • For multiple files, first produce a self-contained document using your usual bundling tool. Input is limited to one million characters; YAML aliases and complexity are bounded too, with a ten-second timeout.

Sources and references

Frequently asked questions

Does successful validation prove the API works?

No. The validator checks part of the description, not server responses, access rights or business rules. No endpoint is called. The report explains the limits of the checks.

How do I check a description split across files?

Bundle it locally into one self-contained document with your usual tooling. This validator retrieves no linked files.

Is OpenAPI 3.2 accepted?

Not in this version. Unsupported versions are reported explicitly rather than treated as syntax errors.

Which checks are performed?

The document is checked against the structural schema for its version. Checks also cover internal JSON Pointer references, 3.1 schema keyword types, operationIds on routes and webhooks, and path parameters. Formats, examples, real data and remaining semantic constraints are not all checked.

Related tools

Keep going with these tools

Tools similar or complementary to this one.

Similar tools

JSON Schema validator

Validate a JSON document against a schema and locate every error precisely.

DevelopmentFeaturedUse this tool

API Request Builder

Build a complete HTTP API request with method, URL, parameters, headers, and body.

DevelopmentUse this tool

Read next