Detecting OpenAPI spec drift with ast buys determinism at the cost of prefixed routers

Code review sees the diff against the last commit, not against a spec written three months ago, according to the tool's author ^[19]. That spec is what generated the SDKs, the frontend types, the API docs and the mock servers ^[18]. The failure it produces is quiet: a generated client keeps calling DELETE /items/{id} and the server answers 405 Method Not Allowed ^[17].

The spec side is a JSON parse. The code side is an ast walk over your sources that picks string literals out of route decorators, and the tool never imports the module, never executes it, and never writes ^[3]. The comparison key is the literal path string: /users/{id} in the spec matches /users/{id} in code and nothing else ^[8].

Method mismatch is the third bucket. On the FastAPI template backend the tool detected 23 routes across 14 paths ^[10], roughly 1.6 methods per path ^[20], so a path-level match tells you nothing about whether DELETE still exists on it. Flipping the implemented POST /login/access-token to PUT in a test spec came back as a method mismatch pointing at backend/app/api/routes/login.py:23 ^[13].

Literal matching produces a false positive, and the author documented it. A router mounted with prefix="/items" serving /{id} does not match a spec's /items/{id} ^[8], so scanning that template against a prefixed spec reported the same route twice: /items/{id} as spec only, /{id} as code only ^[11]. The recommended fix is to normalise the spec side first, and the surest source is the /openapi.json the app actually serves ^[12].

Exit code is 0 whether or not drift is found ^[4]. "A tool that fails your build on day one gets removed on day two. A detector stays," the author wrote ^[5]. The rest of the reasoning is that drift has priorities: a /health endpoint missing from the spec is usually fine, a method mismatch on a payment route is not, and which one fails the build is policy the tool should not decide ^[6]. If you want a gate, the report is machine-readable and you wire it with --json and jq ^[7].

For the numbers to mean anything in your repo, your routes have to be declared as string literals in decorators and your spec paths have to be full paths. A path built with an f-string, @app.get(f"/users/{id}"), is not extracted at all ^[16]. The code-only side under-reports, silently. YAML specs are a future item, so the file you hand it has to be OpenAPI 3.x JSON ^[15].

The demo run scores five findings against two clean paths ^[9][21] on an app drifted on purpose ^[9]. The published test evidence is 15 pure-function tests passing in 0.04s ^[14] plus a wheel build, install and detection run end to end ^[23]; the post does not report how long the template scan took.