Validate OpenAPI 3 / Swagger Specs Online Before CI

Schema errors, broken $ref, missing responses: validate your OpenAPI 3.0–3.2 API contract in the browser.

05.08.2026

7 min read

Share this article:

openapi

swagger

API

validate

REST

Tutorial

Why validate an OpenAPI spec before merging?

An invalid OpenAPI spec blocks client generators, fails API gateway imports, and delays contract reviews. Yet the most common issues — incomplete info, broken internal $ref, unsupported openapi version — often hide in a 500-line YAML diff. FastMinify's online OpenAPI validator checks OpenAPI 3.0, 3.1, and 3.2 schema conformance via @scalar/openapi-parser, entirely in your browser. Paste JSON or YAML: verdict, error paths, and spec stats appear with no server upload. Pair it with the OpenAPI formatter for readable reviews, then explore the API tools hub. If raw JSON syntax is suspect, start with the JSON validator; to optimize payloads once the contract is sound, see our REST API performance guide.

Catch OpenAPI 3.0–3.2 schema errors before CI or gateway import

JSON and YAML accepted — auto-detect with YAML fallback when JSON parse fails

Internal <code>#/…</code> references checked; Scalar issue paths displayed

100% local — your spec never leaves the browser (ideal for internal contracts)

Fast workflow: validate → format → lint (dedicated article coming) → commit

Honest limits and best practices

What validate-openapi does not do

A "valid" verdict means OpenAPI schema conformance — not that your API responds correctly in production.

No fetch of external or remote $ref URLs

No automatic multi-file bundle — one single-file spec per paste

No Swagger 2.0 validation

No security testing (real auth, effective scopes)

512 KiB input limit — huge specs need local tooling or CI

Internal vs external references

#/ references are checked by Scalar. HTTP(S) references to other files are never resolved — the spec must be self-contained for reliable browser validation.

Prefer a single file or bundle upstream with your CI tool

An unresolved external $ref may pass parse but fail elsewhere

Manually verify cross-repo imports after local validation

json-schema-to-openapi and openapi-to-json-schema on the hub for schema pivots

To validate data against a schema: json-schema-validator (dedicated article coming)

CI integration and complements

The browser tool speeds feedback before commit; CI remains the source of truth for teams.

Paste the modified spec before git push — faster than a full pipeline

In CI: Spectral, openapi-cli, or Redocly depending on your stack

Combine with our CI/CD guide for broader automation

Document the target OpenAPI version (3.0 vs 3.1) in the repo README

Review schema breaking changes with json-diff on JSON exports

OpenAPI 3 vs Swagger 2: what the tool checks (and rejects)

OpenAPI 3.x: the modern contract

OpenAPI 3.x describes REST endpoints, request/response schemas, security, and reusable components. FastMinify validates conformance to the OpenAPI meta-schema — not your API's runtime behavior.

Supported versions: 3.0.x, 3.1.x, 3.2.x

Typical required fields: openapi, info.title, info.version, paths

Components schemas, responses, parameters — internal refs resolved

Scalar structural validation — not real HTTP call testing

YAML or JSON: same semantics after parse

Swagger 2.0 explicitly rejected

Documents with a root swagger: "2.0" key are not supported by this tool. The error message is explicit — do not try to validate them here.

Swagger 2 uses swagger; OpenAPI 3 uses openapi

Swagger → OpenAPI 3 migration: use dedicated converters upstream

FastMinify does not claim Swagger 2 validation — avoid false positives

After migration, re-validate with validate-openapi

Hybrid or malformed specs fail at parse before validation

Common errors in real-world specs

Beyond syntax, these structural gaps break CI or SDK generators.

Internal $ref pointing to a missing component — validation failure

HTTP response without description — OpenAPI rule violation

Duplicate or missing operationId — blocks some generators

Schema type incompatible with poorly nested nullable / oneOf

JSON Schema draft mix in components — 3.1 vs 3.0 conformance errors

Validate vs lint vs format

Three distinct intents on the API hub — don't confuse them during PR review.

Validate: OpenAPI schema conformance (Scalar) — valid/invalid verdict

Format: indentation and readability — does not fix semantic errors

Lint: Spectral-style rules (operationId, tags…) — dedicated article coming

Recommended order: validate → format → lint before merge

JSON validator alone is not enough — syntactically valid JSON can be invalid OpenAPI

Validate an OpenAPI spec: step-by-step workflow

Using the OpenAPI validator

The OpenAPI validator parses input (JSON or YAML, max 512 KiB), then calls Scalar validate(). Result: status, first error with line when known, issue list with JSON Pointer paths.

Paste a single-file spec — no external URL fetch

Live debounced validation in the Monaco editor

Results panel: verdict, Scalar issues, paths/operations stats

<code>https://…</code> references never downloaded — intentional limitation

Swagger 2.0 → clear error message, no partial validation

Format before or after validation

The OpenAPI formatter pretty-prints JSON or YAML (2 or 4 space indent, optional key sort). Useful for human review — it does not replace validate.

Readable format for PRs — indentation aligned with the team

Optional key sort for stable diffs

Invalid OpenAPI input may still format if parse succeeds

Chain format → validate to spot errors on indented spec

Large YAML: check the 512 KiB limit before pasting

Scenario — Broken spec before API Gateway import

You export a spec from a design tool and AWS API Gateway / Kong import fails with no detail.

Step 1: Paste into validate-openapi

Open validate-openapi. If parse fails, fix JSON/YAML syntax first — the JSON validator can help on JSON portions.

Step 2: Fix internal $ref

Scalar issues list the path (missing #/components/schemas/User, etc.). Fix the typo or add the referenced component.

Step 3: Format and commit

Run the validated spec through format-openapi, download, open the PR. Re-import into the gateway.

Scenario — Contract review before SDK generation

The mobile team generates a client from the spec — a schema error blocks the entire pipeline.

Step 1: Validate the merged version

Paste the main branch spec into validate-openapi. Invalid verdict → block the release tag.

Step 2: Check info and paths

Complete info fields, every operation has responses with description. Results panel stats help spot empty paths.

Step 3: Minify embedded JSON examples

Bulky embedded examples slow reviews — use the JSON minifier on example payloads once the spec is valid.

Conclusion

Validating an OpenAPI spec before CI saves hours debugging gateway imports or silent SDK generators. Paste, validate, fix Scalar paths — all locally. Format for review, then explore the API hub for lint, JSON Schema conversion, and GraphQL validation.

Validate your OpenAPI spec now

Validate before every PR touching an OpenAPI spec

Do not use this tool for Swagger 2.0 — migrate first

Bundle external $ref upstream for reliable browser validation

Chain validate → format → lint for a complete review

See the REST JSON guide to optimize payloads once the contract is healthy

Share this article

Share this article: