OpenAPI Validator: Lint Your API Spec

What Is OpenAPI Validator?

The OpenAPI Validator is a browser-based tool that parses and validates OpenAPI 3.x and Swagger 2.0 specification files. Paste a JSON or YAML spec, click Validate, and within seconds you see whether the spec is structurally valid, a count of paths and operations, and a list of warnings for missing fields that matter to SDK generators and developer documentation tools.

The tool runs entirely in your browser using the @readme/openapi-parser library loaded on demand. No spec content is sent to any server. It is free to use with no account required.

Use it before committing a spec to version control, before publishing API documentation, or when debugging a spec that a downstream tool like Swagger UI, Stoplight, or an SDK generator is rejecting.

Key Features

• OpenAPI 3.x and Swagger 2.0 support: The validator accepts either format. The underlying @readme/openapi-parser library handles both specification versions, including OpenAPI 3.1.
• JSON and YAML input: The tool attempts JSON.parse first, then falls back to js-yaml for YAML input. You do not need to declare which format you are using.
• Structural validation with precise error messages: When validation fails, error messages from the parser are split on newlines and displayed individually, each with a path reference where applicable.
• Linting warnings: Even when a spec is structurally valid, the tool checks for three common quality issues: missing info.description, operations with neither a description nor a summary, and operations missing an operationId (required for SDK generation). Each warning shows a count so you know the scope of the issue.
• Endpoint and operation counts: After a successful validation, summary tiles show the API title, version string, total path count, and total operation count (across all HTTP methods: get, post, put, patch, delete, head, options, trace).
• Load Example button: Inserts a minimal but complete OpenAPI 3.0 spec with a single /users GET endpoint so you can see what valid output looks like before pasting your own spec.
• Validation history: Previous specs are saved to the browser's IndexedDB database (supporter feature) so you can revisit or restore them without re-pasting.
• 100% client-side processing: Parser and validator run in the browser. Spec content never leaves your machine.

How to Use OpenAPI Validator

Step 1: Paste Your Spec

Click inside the large textarea labeled "OpenAPI Specification (JSON or YAML)" and paste your spec content. The field accepts raw YAML or JSON. For YAML, include the version declaration at the top (openapi: "3.0.0" or swagger: "2.0"). The textarea is monospace and renders approximately 15-20 visible lines.

If you want to see the tool in action before using your own spec, click the "Load Example" button in the top-right corner of the textarea. It loads a minimal OpenAPI 3.0 spec with a /users GET endpoint that returns an array of user objects.

Step 2: Click Validate Spec

Click the "Validate Spec" button below the textarea. The button shows "Validating..." while the parser is running (the @readme/openapi-parser and js-yaml libraries are loaded dynamically on first use, so the first validation may take a moment longer than subsequent ones).

Validation runs against the full spec in memory. For YAML input, the tool first converts it to a JavaScript object with js-yaml, then passes the object to the OpenAPI parser.

Step 3: Review the Validation Result

The result panel appears below the button with one of two headings:

• "✓ Valid OpenAPI Specification" in green — the spec passed structural validation.
• "✗ Validation Failed" in red — the spec has structural errors that must be fixed.

The panel header also shows badge counts: red badges for errors, yellow badges for warnings. You can have a valid spec with warnings — warnings indicate quality improvements, not structural failures.

Step 4: Read the Summary Tiles (Valid Specs)

For specs that pass validation, four summary tiles appear above the error/warning list:

• Title — the value of info.title
• Version — the value of info.version
• Paths — total number of path entries (e.g., /users, /users/{id})
• Operations — total number of HTTP method+path combinations (e.g., a path with GET and POST counts as 2)

These numbers are useful for confirming you are validating the right file, especially when managing multiple spec versions.

Step 5: Address Warnings

Three warning types are surfaced even on valid specs:

1. Missing info.description — the spec lacks an overall API description. This appears in Swagger UI and developer portals and helps users understand what the API does.
2. Operations missing description or summary — reported as a count (e.g., "3 operation(s) missing description or summary"). Both description and summary are checked; if either is present, no warning is raised for that operation.
3. Operations missing operationId — SDK generators (OpenAPI Generator, Kiota, etc.) use operationId to name generated methods. Missing values cause generators to fall back to path-based names, which are often verbose and inconsistent.

Practical Examples

Example 1: Finding a Missing Required Field

Suppose you paste a Swagger 2.0 spec that references a $ref pointing to a schema definition that does not exist. The validator will return:

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

Each line from the parser error is shown as a separate error entry. Fix the $ref path or add the missing definition, then re-validate.

Example 2: Valid Spec with Quality Warnings

A spec with all required structural elements but no operationId values on its endpoints passes validation but shows:

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

The spec can be used in tools like Swagger UI immediately. Address the warnings before running it through an SDK generator.

Example 3: Checking a Large Spec at a Glance

After pasting a 500-path internal API spec, the summary tiles show "Paths: 147" and "Operations: 312". If you expected 150 paths, you know to investigate why three paths are missing before committing the spec.

Tips and Best Practices

Validate after every structural change. Adding a new path, changing a $ref, or modifying a schema can introduce errors that only appear when the full spec is parsed. Validation takes under two seconds, so run it frequently.

Treat operationId warnings as blockers for SDK workflows. If you are generating client SDKs from your spec, all operations must have unique operationId values. Leaving them unset means generated method names will be derived from paths (e.g., getUsersUserIdOrders instead of listOrders), which is difficult to work with.

Use the Load Example as a template start. The built-in example is a complete, valid, minimal OpenAPI 3.0 spec. Copy it from the textarea after loading it and use it as the skeleton for a new spec rather than starting from a blank file.

Separate structural validity from semantic correctness. The validator confirms that your spec follows the OpenAPI schema. It does not confirm that your spec accurately describes your actual API. Run integration tests or contract tests to verify semantic accuracy.

Fix errors from the top of the list down. A single missing schema definition can cause cascading $ref errors throughout the spec. Address the root error first and re-validate before working through secondary errors.

Common Issues and Troubleshooting

"Parse error: ..." — the input is neither valid JSON nor valid YAML. Common causes: a trailing comma in JSON ({"key": "value",}), inconsistent YAML indentation, or a tab character used for YAML indentation (YAML requires spaces). Fix the syntax and re-validate.

Validation fails on a spec that Swagger UI accepts. Swagger UI is lenient and will render specs with some structural violations. The @readme/openapi-parser applies strict validation per the official JSON Schema for OpenAPI. The errors shown here reflect real specification violations even if Swagger UI silently ignores them.

Warnings appear even after adding descriptions. The tool checks for both description and summary on operations, but checks info.description separately. Confirm that you added description inside info, not only on individual paths.

The tool seems slow on first use. The @readme/openapi-parser and js-yaml libraries are loaded dynamically on the first validation click. Subsequent validations in the same browser session will be faster because the modules are already in memory.

Long error messages are cut off. Error messages from the parser are displayed in full. If a message is long, the text wraps within its row. Scroll the page to read the full message if it extends below the visible area.

Privacy and Security

The OpenAPI Validator processes your spec entirely in the browser. The @readme/openapi-parser library runs locally — no spec content is sent to any external service or server. This means you can safely validate internal API specs, private endpoint paths, and proprietary schema definitions without risk of exposure. The tool works fully offline once the page and parser library have loaded.

Frequently Asked Questions

Is OpenAPI Validator free to use? Yes. There is no cost, account, or usage cap. All validation features are available without signing in.

What OpenAPI versions are supported? The tool accepts Swagger 2.0, OpenAPI 3.0.x, and OpenAPI 3.1.x. The underlying @readme/openapi-parser handles all three versions. The textarea placeholder reads "OpenAPI 2.0 / 3.0 / 3.1" to reflect this.

Can I paste YAML or does it need to be JSON? Both formats work. The tool tries JSON.parse first, and if that fails it uses js-yaml to parse YAML. You do not need to convert your spec before pasting.

Does the tool validate my actual API endpoints? No. The validator checks that your spec file is structurally correct according to the OpenAPI schema. It does not make any HTTP requests to the servers or paths listed in your spec.

Why does my spec fail here but work in Swagger UI? Swagger UI renders specs with some tolerance for errors. This validator applies strict schema validation, which will catch issues that Swagger UI silently ignores. Both behaviors are by design — this tool catches spec quality problems early, before they cause issues in stricter consumers like SDK generators.

What does "operationId required for SDK generation" mean? SDK generators like OpenAPI Generator and Kiota name generated methods after operationId values. Without them, generators fall back to constructing names from the HTTP method and path (e.g., getApiV1UsersUserIdOrdersOrderId). Adding concise, unique operationId values to every operation produces much cleaner generated client code.

Are there false positives in the warnings? The three warning checks are conservative. The info.description check triggers only when the field is absent or empty. The operation description check counts only operations missing both description and summary — having either one suppresses the warning for that operation. The operationId check is strict: every operation that lacks one is counted.

Can I validate a spec file rather than pasting it? The tool accepts pasted text only — there is no file upload button. Open your spec file in a text editor, select all, and paste the content into the textarea.

Does the history panel save my spec content? Yes. When you validate a spec successfully, the tool saves an entry to your browser's IndexedDB history (supporter feature) containing the input spec and the validation summary. History is local to your browser and is never synced to a server.

What happens if I paste an empty spec? The Validate button is disabled when the textarea is empty (disabled={!input.trim()}). You must enter at least one non-whitespace character before the button becomes clickable.

Related Tools

• API Mock Generator — generate mock response data from your validated spec to use in frontend development.
• API Design Suite — design and iterate on API structure before exporting to OpenAPI format.
• JSON Formatter — format and validate the JSON structure of your spec before pasting it into the validator.

Try OpenAPI Validator now: OpenAPI Validator