openapi-drift 0.1.0

╔════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                            ║
║                    ██████╗ ██████╗ ███████╗███╗   ██╗ █████╗ ██████╗ ██╗                   ║
║                   ██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔══██╗██╔══██╗██║                   ║
║                   ██║   ██║██████╔╝█████╗  ██╔██╗ ██║███████║██████╔╝██║                   ║
║                   ██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██╔══██║██╔═══╝ ██║                   ║
║                   ╚██████╔╝██║     ███████╗██║ ╚████║██║  ██║██║     ██║                   ║
║                    ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝     ╚═╝                   ║
║                                                                                            ║
║                            ██████╗ ██████╗ ██╗███████╗████████╗                            ║
║                            ██╔══██╗██╔══██╗██║██╔════╝╚══██╔══╝                            ║
║                            ██║  ██║██████╔╝██║█████╗     ██║                               ║
║                            ██║  ██║██╔══██╗██║██╔══╝     ██║                               ║
║                            ██████╔╝██║  ██║██║██║        ██║                               ║
║                            ╚═════╝ ╚═╝  ╚═╝╚═╝╚═╝        ╚═╝                               ║
║                                                                                            ║
║                        does the service still do what the spec says                        ║
║                                                                                            ║
╚════════════════════════════════════════════════════════════════════════════════════════════╝

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

This answers two questions:

• Does the deployed service still do what this says?
• Can a machine read it and act on it?

pip install openapi-drift

openapi-drift openapi.json                          # static checks
openapi-drift https://api.example.com/openapi.json --live
openapi-drift openapi.json --live --base-url https://api.example.com

Exits 0 clean, 1 on drift, 2 when it could not check.

What it is not

The check nobody else runs

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

That cost a working week to learn on a real spec that passed every other check. It is reported as ref_in_response, and --allow-refs silences it if nothing consuming your document does function calling.

What it finds

Drift — exits 1:

Warnings — exit 0 unless --warnings-as-errors:

untyped_schema · no_operation_id · no_description · relative_server · undocumented_field

It will not tell you it passed when it did not

An empty document, a document with no paths, and one where every operation needs an argument all exit 2, not 0. A pass on something never examined is the most dangerous sentence a build tool can say, and it is the reason this exists at all.

In CI

- uses: vince-gonzalez/openapi-drift@v1
  with:
    spec: https://api.example.com/openapi.json
    live: "true"

Or directly:

- run: pip install openapi-drift
- run: openapi-drift openapi.json --live

Only safe calls

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

Licence

MIT.