OpenAPI Spec Validator

Valid is a low bar

A specification can satisfy the JSON Schema for OpenAPI and still be nearly useless. Validation confirms structure: required fields present, types correct, references resolvable. It says nothing about whether the spec describes what the API actually does, whether the examples work, or whether a generated client will function. Most of the real problems sit above the validator's reach.

Version differences that bite

Swagger 2.0 and OpenAPI 3.x are structurally different, not cosmetically. Bodies moved from a parameter with in: body to a dedicated requestBody. definitions became components/schemas. Host, basePath and schemes collapsed into a servers array. Tools frequently accept both and behave differently, so a spec converted by a machine and never reviewed often carries fragments of the old shape that validate and mislead.

Unresolvable and circular references

A $ref pointing at a missing definition or an external file that has moved fails at generation rather than validation in some tooling. Circular references are legal and represent genuine recursive structures, but many code generators either loop forever or silently truncate the type. If a generated client is missing a nested field, a circular reference is a likely cause.

Undocumented responses are the common gap

Specs routinely document 200 and nothing else. Generated clients then have no type for the error body, and consumers write their own guesses. Every status code the API can return, with its schema, belongs in the spec — particularly 400, 401, 403, 404 and 422, since those are the ones client code has to handle.

Examples must be real

Hand-written examples drift from the schema and from the implementation, and nothing catches it unless examples are validated against their own schema. An example that contradicts its schema is worse than none, because documentation readers trust it and build against it. Generating examples from the schema, or validating them in CI, keeps them honest.

Generate the spec, or verify it against the code

A specification maintained by hand alongside an implementation diverges — not gradually, but at the first hurried change. Either generate it from code annotations, or run contract tests that exercise the real API against the spec in CI. A spec nobody verifies describes the API as somebody once intended it, which is the state most public API documentation is in.