openapi-drift

An OpenAPI document is a promise about a service, and nothing keeps the two together. This checks whether the service still does what the document says, and whether a machine can still read the document at all.

Install it Use as a GitHub Action

pip install openapi-drift · MIT · safe calls only, never writes

What it does

An OpenAPI document is a promise about a service, and nothing keeps the two together. It quietly becomes a description of what the service used to do, and every consumer finds out one failed call at a time.

pip install openapi-drift
openapi-drift openapi.json
openapi-drift https://example.com/openapi.json --live

The check that is easy to skip

A response schema behind a $ref is correct, valid, and useless to the tools that turn an operation into a function signature, because they do not dereference. A validator sees a schema; a converter sees an argument with no type. The document passes everything and cannot be used.

That is not hypothetical. It cost a week on a specification that passed every other check.

What it is not

Not a fuzzer — it calls what you documented rather than generating traffic hunting for crashes. Not a syntax validator — a perfectly well-formed document can be unreadable by a machine.

Only safe calls

--live calls parameterless GETs only. A path with a placeholder or a required parameter is skipped rather than guessed at, because a guessed value reports drift that is the checker's fault. Nothing is ever written.

PyPI Source

How it works

Point it at your documentopenapi-drift openapi.json, or a URL.
Add <code>--live</code> to call the serviceIt calls every parameterless GET and compares what comes back to what the document promised.
Put it in CIThe document and the service drift apart quietly. Every consumer finds out one failed call at a time; this finds out on the commit that caused it.

What it checks

The $ref trap, reported not silently fixedA response schema behind a $ref is valid and useless to a consumer that does not dereference. This is a known problem with libraries built to solve it — openapi-schema-ref-parser is one. Those dereference it for you; this reports it, so the document gets fixed rather than every consumer working around it.

Live comparisonNot just the document. What the service actually returns.

Only safe callsParameterless GETs. A path with a placeholder or a required parameter is skipped rather than guessed at — a guessed value reports drift that is the checker's fault.

It never writesNo POST, no PUT, no DELETE. Ever.

Not a fuzzerIt calls what you documented rather than generating traffic hunting for crashes.

A GitHub ActionOne step in a workflow, pointed at a path or a live URL.

Specifications

Install	pip install openapi-drift
License	MIT
Action	vince-gonzalez/openapi-drift
Source	vince-gonzalez/openapi-drift

Questions

Is this a schema validator?: No, and that is the point. A perfectly well-formed document can be unreadable by the tooling that has to consume it.
Will it hit my production API?: Only if you pass --live, and only with parameterless GETs. It never writes anything.
Why does the $ref thing matter?: It cost a week on a specification that passed every other check.