oas-drift: a zero-dependency CLI that catches drift between OpenAPI specs and Python code

A zero-dependency checker for OpenAPI drift

A developer posting as sunnydachs has released oas-drift, an open-source command-line tool that compares an OpenAPI specification against the routes actually present in a Python codebase and reports where the two disagree. In the announcement on dev.to, the author frames it as an answer to a familiar failure mode: SDKs, frontend types, API documentation and mock servers are all generated from the spec, so once an implementation quietly diverges, everything generated from it becomes subtly wrong — a generated client can keep calling a DELETE endpoint that the server now answers with a 405.

The tool takes an OpenAPI 3.x JSON file plus a source root and sorts disagreements into three categories: endpoints defined in the spec but with no matching route in code, routes implemented in code but absent from the spec, and paths that match while the HTTP method differs. A scan runs read-only against a directory via a --spec flag, and a -- flag produces structured output suitable for scripting.

A detector, not a gate

One design choice stands out: oas-drift exits with code 0 whether or not it finds drift. According to the author, this is what separates a detector from a gate. Tools that break the build on first contact tend to get uninstalled the next day, and which drift matters is a policy question — a /health endpoint missing from the spec is usually harmless, while a method mismatch on a payment route is not. Rather than encoding that judgment, the tool reports and lets teams decide; anyone who does want enforcement can pipe the JSON report through jq in CI.

The implementation is also conservative on the safety front. It parses source files with Python's ast module and never imports, executes or writes anything, which keeps reports deterministic: identical input yields an identical output. It runs on the Python 3.11+ standard library alone, with no third-party packages and no language-model involvement. The author describes it as a sibling to other deterministic checkers shipped this month, including doc-drift, which compares READMEs against code.

Literal path matching, tested on a real codebase

The matching rule is deliberately strict: /users/{id} in the spec matches /users/{id} in code and only that. Router prefixes are not resolved, so a FastAPI router mounted with a prefix plus a relative route path will not pair up with the fully qualified path in the spec. The author validated this against the backend of FastAPI's official full-stack-fastapi-template — 25 files, 14 paths and 23 routes detected — and found that scanning it with a prefixed spec produces exactly the false-positive pair the rule predicts: the same route reported once as spec-only and once as code-only. The recommendation is to normalize the spec side first, ideally starting from the /openapi. the application itself serves.

Reported testing, per the dev.to post, covers 15 pure-function tests with no network or disk fixtures running in about 0.04 seconds, an end-to-end check of the wheel build, install and scan path, and a deliberately planted method mismatch on a login route that the tool caught precisely. These figures are the author's own rather than an independent review.

Documented limitations

The README is upfront about the gaps. Only OpenAPI 3.x JSON is supported, with YAML listed as future work. Route paths built with f-strings, such as @app.get(f"/users/{id}"), are not extracted; only string literals are. And the comparison covers routes and HTTP methods only — request and response schema checking is left for later versions.

Why it matters

Spec-first development only works if something verifies both sides of the contract, and ordinary code review compares a diff against the last commit, not against a spec written months earlier. Drift between spec and implementation is a root cause of broken generated SDKs, wrong client types and misleading docs. A small, dependency-free, read-only checker that finishes in milliseconds is cheap enough to run routinely, and because its output is structured, teams can layer their own severity policy on top instead of inheriting the tool's judgment. The project is published on GitHub as a personal open-source effort without warranty, with issues as the feedback channel.