OpenAPI validator

An OpenAPI document describes an HTTP API: its paths, the operations on each, their parameters, request bodies and responses. Documentation sites, code generators, mock servers and test tools all read it, and each reacts differently to a mistake. One renders a blank page, another generates code that doesn't compile, a third silently skips the endpoint. Validating first saves the guesswork.

This validator checks the rules of OpenAPI 3.0, 3.1 and Swagger 2.0 that cause trouble in practice. Required fields must be there: openapi, info.title, info.version, paths, a description on every response. Every {param} in a path needs a matching path parameter with required: true. Status codes must be real, operationIds unique, and parameters not declared twice. Every $ref must point to something, security requirements must name a defined scheme, and examples must match their schemas.

Each problem shows the JSON pointer of where it is, such as /paths/~1pets~1{petId}/get, and for JSON input the line number. Errors break the spec for most tools; warnings are things that work but are usually unintended, such as a schema nothing uses.