About OpenAPI Validator

Validate OpenAPI/Swagger specifications with detailed error reporting and compliance checking. Part of the DevTools Surf developer suite. Browse more tools in the API / Config collection.

Use Cases

• Validate an OpenAPI 3.0 or 3.1 specification before publishing it to a developer portal.
• Catch $ref resolution errors, missing required fields, and schema type mismatches in a large spec.
• Run design-time API governance rules (consistent naming, required descriptions, error schemas) before implementation.
• Validate imported or auto-generated OpenAPI specs from Postman or Insomnia before use.

Tips

• Validate after every schema addition, not just at the end — catching issues early prevents cascading errors from $ref mismatches.
• Check for unused components in the components/schemas section — they won't cause validation failures but create dead code that confuses consumers.
• Enable spectral rules alongside structural validation to check design conventions (plural path names, consistent casing, status code completeness).

Fun Facts

• The OpenAPI Validator in Swagger UI uses Ajv (Another JSON Validator) to validate specifications — the same library is used to validate JSON schemas in thousands of other tools.
• Common OpenAPI mistakes caught in production: missing 401/403 error schemas (47% of APIs), inconsistent casing in path parameters (31%), and missing content-type definitions (28%) — according to a 2022 API quality analysis.
• Spectral, the open-source API linter built by Stoplight (2019), introduced ruleset-based OpenAPI quality checking beyond structural validation — checking naming conventions, completeness, and style — and is now the de facto standard for API governance.

FAQ

Does it support both OpenAPI 3.0 and 3.1?

Yes — version is auto-detected from the openapi field. 3.0 and 3.1 have different JSON Schema dialects; the validator applies the correct rules for each version.

What's the difference between structural validation and linting?

Structural validation checks that the spec is valid per the OpenAPI JSON Schema (required fields, type correctness, $ref targets). Linting checks design conventions (naming, completeness) that the spec doesn't enforce.

Does it validate Swagger 2.0?

Yes — Swagger 2.0 (swagger: '2.0') is detected and validated against the Swagger 2.0 JSON Schema. Error messages reference Swagger 2.0 spec sections.