Verify your FastAPI app against its OpenAPI spec
FastAPI writes the OpenAPI document for you, which makes it easy to believe the document and the server cannot disagree. They can. Any handler that returns a Response directly, any JSONResponse built from a raw database row, any model that is looser than the data it describes, puts something on the wire that the document does not describe. apidrifter sends one request per operation to the running app, checks every response against the document FastAPI serves, and tells you which side to change.
- 01 Find the OpenAPI document. Details
- 02 Start the FastAPI app. Details
- 03 Run apidrifter against it. Details
- 04 Read the findings and pick a side. Details
- 05 Make it automatic. Details
Where the FastAPI spec comes from
FastAPI serves the generated document at /openapi.json on the running app (and the Swagger UI at /docs). It is built from the path operation signatures, the Pydantic models used as response_model and request bodies, and the responses= mapping on each route. apidrifter can read it straight from that URL, so there is nothing to export first. If you want a file to diff in CI, app.openapi() returns the same document; the example has a two-line export_spec.py that prints it.
The document is OpenAPI 3.1, so optional fields appear as anyOf with null and nullable: true is never used. apidrifter reads both forms.
Start the app
The commands below use the example from the repository; for your own app, start it the way you normally do and note the port.
git clone https://github.com/apidrifter/apidrifter && cd apidrifter/examples/fastapi
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --port 8000Run apidrifter
npx -y apidrifter run http://localhost:8000/openapi.json --base-url http://localhost:8000 --format markdownThe spec argument is the URL FastAPI serves; plain http:// is accepted for localhost only. Path parameters get their values from examples=[...] on Path(...), request bodies from a model's json_schema_extra example, so the example runs without a plan file. If your own app has no examples, run apidrifter plan with the same URL, fill the slots it lists, and add --plan filled.json.
Read the findings and decide which side to fix
This is the real report for the example, which has one deliberate mismatch. Every finding carries a stable rule ID, the operation and JSON location, and two fixes.
## Verification report
2 breaking, 0 warning, 0 info.
Coverage: 4 of 4 operations observed, 0 observations matched no operation.
### Breaking (2)
- `response-null-not-allowed` at `GET /todos/{todo_id} > response 200 > application/json > /due_date` (observation 2): response body at /due_date: value is null but the schema does not allow null
- If the spec is the source of truth: Return a non-null value in response body at /due_date.
- If the implementation is the source of truth: Allow null at paths["/todos/{todo_id}"].get.responses["200"].content["application/json"].schema.properties["due_date"] (add "null" to type, or nullable: true in OpenAPI 3.0).The example's Todo model declares due_date: str. The store has a row whose due_date is None, and the handler returns JSONResponse(row), which skips response_model validation, so the null reaches the client while the document promises a string. A client generated from the document decodes due_date into a non-optional string and fails on that row; that is why the finding is breaking and the exit code is 1.
Which side is right? A todo without a due date is a legitimate state, so the implementation is the source of truth and the model is wrong: change the annotation to due_date: str | None = None and FastAPI regenerates the document with anyOf: [string, null]. If the product rule were that every todo has a due date, the store would be wrong instead, and the handler should go back to returning the row through response_model so FastAPI refuses a bad row rather than serving it. The finding cannot know which; the person or agent who made the change can.
Make it automatic
The check is only useful if it runs every time a route or a model changes, which is exactly when nobody remembers to run it. Three pieces make it automatic, and the example directory carries all three.
First, an instructions file. Paste this into CLAUDE.md,AGENTS.md or whatever file your coding agent reads; it is the paragraph from the agents page with this framework’s spec location and port filled in.
## API contract checks
When you add or change an HTTP endpoint or a Pydantic model that feeds the OpenAPI document, verify the
implementation against the spec before opening a pull request:
1. Start the service locally and note its port (8000).
2. Run `npx -y apidrifter plan http://localhost:8000/openapi.json --out plan.json` to see which
parameter and body values the engine cannot infer, and write a filled plan with
realistic values from the codebase.
3. Run `npx -y apidrifter run http://localhost:8000/openapi.json --base-url http://localhost:8000 --plan filled.json --format markdown`.
Plain http:// is only allowed for localhost. Never put real credentials in the plan,
the command line or the report; use `--bearer-env VAR` for tokens.
4. For each finding, decide which side is the source of truth: the spec (fix the
implementation) or the implementation (fix the spec). Do not loosen the spec just to
make the report clean.
5. Fix and rerun until there are no findings at or above the fail level, then paste the
Markdown report into the pull request description.Second, a job in CI that starts the app and runs the check with--fail-on breaking. The example’s.github/workflows/apidrifter.yml has the full file; this is the live-check job.
live-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install -r requirements.txt
- name: Start the app
run: |
uvicorn main:app --port 8000 &
for i in $(seq 1 20); do curl -sf http://localhost:8000/health && break; sleep 0.5; done
- name: Verify the implementation against the spec
run: |
npx -y apidrifter run http://localhost:8000/openapi.json --base-url http://localhost:8000 \
--format markdown --fail-on breaking | tee report.md >> "$GITHUB_STEP_SUMMARY"
exit "${PIPESTATUS[0]}"The Claude Code plugin adds a PostToolUse hook that reminds the agent to run the check after it edits an OpenAPI document or a file under routes, controllers, handlers or api (for FastAPI, that is usually a routers directory; the hook is a shell script and the pattern is one line to change). The example's workflow also has a spec-diff job: it regenerates openapi.json with export_spec.py, fails if the committed snapshot is stale, and runs apidrifter/action@v1 against the base branch so a breaking change to the document is flagged before the live check even starts.
Frequently asked questions
- FastAPI validates responses with response_model, so how can the server drift from the document?
- Validation only happens on the return path that goes through response_model. Returning a Response or JSONResponse directly, using response_model=None, or serializing with a custom response class bypasses it, and a model that is looser than the data (an Optional that should be required, an int that is really a string) is documented as the model says, not as the data is. apidrifter checks from the outside, so it sees what a client sees.
- Can apidrifter read the spec from the running FastAPI app?
- Yes. Pass http://localhost:8000/openapi.json as the spec argument. Plain http:// is accepted for localhost only; a staging host must be https://. For CI diffs, print app.openapi() to a file and commit it, as the example's export_spec.py does.
- Should I fix the model or the handler?
- Decide what the change intended. If the data is right and the model is stale, fix the model (that regenerates the document). If the document is the published contract that clients are generated from, fix the handler or the data. Do not widen the model just to make the report clean; the two fixes in each finding exist so you can pick on purpose.
Example: examples/fastapi in the repository. Last reviewed against apidrifter 0.1.0.