OpenAPI Validator: Catch Structural Mistakes
An OpenAPI spec that's syntactically valid JSON or YAML can still be missing fields that consuming tools depend on — a missing responses object breaks code generators, a missing info.version confuses documentation tooling. This validator checks for exactly those structural requirements, working with either JSON or YAML input.
Covers the most common structural mistakes, not full JSON Schema compliance against the official OpenAPI meta-schema.
What Makes a Spec Structurally Valid
Beyond just being parseable JSON or YAML, a usable OpenAPI document needs a version declaration, an info block with a title and version, at least one path, and every operation under those paths needs to declare its possible responses — tools consuming the spec (documentation generators, client SDK generators, mock servers) all assume these fields exist.
Why operationId Gets a Warning, Not an Error
operationId isn't required by the OpenAPI spec itself, but it's what most client code generators (openapi-generator, swagger-codegen) use to name the generated function for each operation — without it, generators typically fall back to an auto-generated name that's harder to work with, so this tool flags its absence for you to consider.
Practical Examples
Catching a Missing Responses Block
An operation that forgot to declare its responses.
- 1.Paste the spec
- 2.Result: error naming the exact operation missing responses
What Gets Checked
- Required openapi/swagger version field
- Required info.title and info.version
- Non-empty paths object
- Every operation has a responses object
- operationId presence (warning)
Good Use Cases
- Catching structural mistakes before publishing docs
- Reviewing a spec change in a pull request
- Sanity-checking a spec generated by another tool
- Debugging why a code generator or Swagger UI rejects your spec
Frequently Asked Questions
What does this actually validate?
Structural requirements from the OpenAPI spec: a valid openapi/swagger version field, a required info object with title and version, a non-empty paths object, and that every operation under paths has a responses object. It also warns when an operation is missing an operationId, which many client-generator tools rely on.
Is this a full JSON Schema validator against the official OpenAPI schema?
No — this repo doesn't bundle a JSON Schema validation library, so this is a targeted structural checker covering the most common real mistakes, not a complete spec-compliance validator. For full compliance validation, use a dedicated tool like the official Swagger/OpenAPI validator or the `spectral` CLI.
Does it support both JSON and YAML specs?
Yes — input is parsed as JSON first (if it starts with { or [), otherwise it's parsed with this site's best-effort YAML parser (the same one used by the docker-compose/Kubernetes YAML validators).
Why does it warn instead of error on a missing operationId?
A missing operationId doesn't violate the OpenAPI spec itself — an operation is still valid without one — but many client SDK generators use it to name generated methods, so its absence is flagged as a best-practice warning rather than a hard structural error.
Is my spec sent anywhere?
No, all parsing and validation happens locally in your browser.