How do I validate an OpenAPI spec?

Paste your OpenAPI 2.x or 3.x spec (YAML or JSON) and click Validate. Specway uses @apidevtools/swagger-parser — the same library most CI pipelines use — to parse the spec, resolve $refs, and check the document against the OpenAPI JSON Schema. If valid, you get a summary (title, version, path/operation/schema counts). If invalid, you get the exact error path.

What's the difference between OpenAPI 2.0 (Swagger) and 3.x?

OpenAPI 3.0 (released 2017) reorganized the spec significantly: components/schemas replaces definitions, requestBody replaces consuming a body via parameters, servers replaces host+basePath+schemes. OpenAPI 3.1 (2021) aligned with JSON Schema 2020-12. The validator accepts all three. If you're still on 2.0, use the Swagger 2 → OpenAPI 3 converter to migrate.

What's the most common reason a spec fails validation?

Unresolved $refs — the spec references a schema or parameter that doesn't exist or isn't reachable. Other top causes: missing required fields (info, paths, version), wrong JSON Schema in component definitions, invalid HTTP methods, security scheme references that don't match a defined scheme.

Does the validator follow $ref to external files?

No — this validator runs in the browser and can't fetch arbitrary URLs (CORS, security). External $refs (URLs or relative paths) will fail to resolve. For multi-file specs, use swagger-parser locally in a Node script, or merge them into one document first using a tool like @redocly/cli bundle.

My spec validates but my SDK generator still fails — why?

Validation checks that the spec conforms to the OpenAPI standard. SDK generators have additional requirements: every operation needs an operationId, every schema needs a name, every response needs an example. The OpenAPI Linter tool checks for these "documentation quality" issues that pass validation but break tooling.

Why do AI tools generate specs that don't validate?

LLMs hallucinate fields and structure. The most common error pattern: making up component names that aren't defined, using OpenAPI 2.0 syntax in a 3.x document (or vice versa), and inconsistent response shapes. Always run AI-generated specs through this validator before trusting them — and feed validation errors back into the prompt for a fix.

Can I validate multiple specs at once?

Not in the browser tool. For CI / batch validation, run swagger-parser on each spec in a Node script, or use Specway — it auto-validates every spec on import and surfaces errors in a normalized form across your whole catalog.

How do I validate an OpenAPI spec?

Paste your OpenAPI 2.x or 3.x spec (YAML or JSON) and click Validate. Specway uses @apidevtools/swagger-parser — the same library most CI pipelines use — to parse the spec, resolve $refs, and check the document against the OpenAPI JSON Schema. If valid, you get a summary (title, version, path/operation/schema counts). If invalid, you get the exact error path.

What's the difference between OpenAPI 2.0 (Swagger) and 3.x?

OpenAPI 3.0 (released 2017) reorganized the spec significantly: components/schemas replaces definitions, requestBody replaces consuming a body via parameters, servers replaces host+basePath+schemes. OpenAPI 3.1 (2021) aligned with JSON Schema 2020-12. The validator accepts all three. If you're still on 2.0, use the Swagger 2 → OpenAPI 3 converter to migrate.

What's the most common reason a spec fails validation?

Unresolved $refs — the spec references a schema or parameter that doesn't exist or isn't reachable. Other top causes: missing required fields (info, paths, version), wrong JSON Schema in component definitions, invalid HTTP methods, security scheme references that don't match a defined scheme.

Does the validator follow $ref to external files?

No — this validator runs in the browser and can't fetch arbitrary URLs (CORS, security). External $refs (URLs or relative paths) will fail to resolve. For multi-file specs, use swagger-parser locally in a Node script, or merge them into one document first using a tool like @redocly/cli bundle.

My spec validates but my SDK generator still fails — why?

Validation checks that the spec conforms to the OpenAPI standard. SDK generators have additional requirements: every operation needs an operationId, every schema needs a name, every response needs an example. The OpenAPI Linter tool checks for these "documentation quality" issues that pass validation but break tooling.

Why do AI tools generate specs that don't validate?

LLMs hallucinate fields and structure. The most common error pattern: making up component names that aren't defined, using OpenAPI 2.0 syntax in a 3.x document (or vice versa), and inconsistent response shapes. Always run AI-generated specs through this validator before trusting them — and feed validation errors back into the prompt for a fix.

Can I validate multiple specs at once?

Not in the browser tool. For CI / batch validation, run swagger-parser on each spec in a Node script, or use Specway — it auto-validates every spec on import and surfaces errors in a normalized form across your whole catalog.

OpenAPI Validator (2026)

Validate OpenAPI 2.x / Swagger and OpenAPI 3.x specs against the official schema. Powered by @apidevtools/swagger-parser, the same library most CI pipelines use. Runs entirely in your browser.

OpenAPI / Swagger spec

What validation checks

Document structure: required top-level fields (openapi, info, paths) exist; types match.
Schema validity: component schemas conform to JSON Schema (2020-12 for OpenAPI 3.1, draft-04 for 3.0).
$ref resolution: internal references point to existing nodes. (External $refs need a local resolver.)
Operation shape: each operation has valid parameters, requestBody, responses.
Security definitions: security schemes are defined where referenced.

What it doesn't check (use the linter for these)

Whether every operation has an operationId.
Whether descriptions are present and meaningful.
Whether responses include examples.
Whether parameter names follow a consistent style.
Whether you're reusing components vs inlining the same shape repeatedly.

Validation in your CI

If your spec lives in a repo, validate on every PR. A typical npm script:

{
  "scripts": {
    "validate-spec": "swagger-parser validate openapi.yaml"
  }
}

Or, if you use Specway, validation runs automatically on every push and the build refuses to ship docs from an invalid spec.

Related tools

OpenAPI Viewer

Render the validated spec as interactive docs.

OpenAPI Linter

Catch documentation-quality issues.

Swagger 2 → OpenAPI 3

Migrate older specs to OpenAPI 3.x.

YAML ↔ JSON

Convert between YAML and JSON.

Frequently asked questions

Ship API docs that stay this clean

Specway turns your OpenAPI spec into a branded developer portal — auto-synced, searchable, with built-in playground and code samples in every language. Free tier available.

Try Specway free