OpenAPI 3 Spec Validator (Swagger)

Catch OpenAPI spec mistakes before they break code generation, mock servers, or developer docs. This validator parses your YAML / JSON spec, checks the structure against OpenAPI 3.0 / 3.1 rules, and flags common issues: missing required fields, undefined $ref targets, duplicate operationIds, missing response definitions, security scheme references without matching definitions.

How to use the OpenAPI 3 Spec Validator (Swagger)

Paste your OpenAPI spec (YAML or JSON — auto-detected). The validator runs ~25 checks: required top-level fields (openapi, info, paths), path operation structure, schema definitions, $ref resolution, duplicate operationIds, parameter conflicts, response schema validity.

About OpenAPI 3 Spec Validator (Swagger)

OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. A spec is a single YAML or JSON document that describes endpoints, request / response shapes, authentication, error codes — enough for tools to generate client SDKs, server stubs, mock servers, and interactive documentation.

OpenAPI 3.0 (2017) reorganized the older Swagger 2.0 spec, added components for reuse, and supported richer schemas. 3.1 (2021) made the schema language fully JSON Schema Draft 2020-12 compatible (resolved long-standing incompatibilities). Most tools support both.

Common spec mistakes this validator catches:

  • Missing operationId — code generators need it to name functions.
  • Duplicate operationIds — undefined behavior in most generators.
  • Broken $ref — referencing a schema component that doesn't exist.
  • Path parameter mismatch — /users/{id} declared without a corresponding {id} in parameters.
  • Missing response definitions — every operation must have at least one response.
  • Security scheme reference without definition — citing a security scheme not declared in components.securitySchemes.
  • Empty servers — spec without a server URL.

Common use cases

  • Pre-merge check — confirm a spec change doesn't break the contract.
  • Code generation troubleshooting — find the spec error before debugging the generator.
  • Migration from Swagger 2 to OpenAPI 3 — verify the converted output.
  • Contract review — sanity-check a partner-provided API spec before consuming it.

Frequently asked questions

Does it support OpenAPI 3.1 features (webhooks, jsonSchemaDialect)?
Yes — handles both 3.0.x and 3.1.x. Doesn't enforce 3.1-only constraints when version is set to 3.0.

Will it validate against my custom schema extensions (<code>x-*</code>)?
No — extension fields are allowed but not validated. They're by design tool-specific.

Is this a replacement for Spectral?
No — Spectral runs many more lint rules and supports custom rulesets. This is a fast first-pass check.