---
title: "Verify your FastAPI app against its OpenAPI spec"
description: "FastAPI generates the OpenAPI document from your type hints. How to run apidrifter against the live app, read a real finding, and make the check automatic."
date: 2026-11-03
author: API Drifter
canonical: https://apidrifter.com/guides/fastapi/
example: https://github.com/apidrifter/apidrifter/tree/main/examples/fastapi
license: Apache-2.0
---

# Verify your FastAPI app against its OpenAPI spec

By API Drifter. Canonical: https://apidrifter.com/guides/fastapi/. Runnable example: https://github.com/apidrifter/apidrifter/tree/main/examples/fastapi

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.

## Steps

1. **Find the OpenAPI document.** 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.
2. **Start the FastAPI app.** Start the service locally and note its port; the example listens on 8000. apidrifter accepts plain http:// for localhost only.
3. **Run apidrifter against it.** Run npx -y apidrifter run http://localhost:8000/openapi.json --base-url http://localhost:8000 --format markdown. One request per operation is built from the spec's examples; if an operation is skipped for missing values, run apidrifter plan, fill the slots, and pass --plan filled.json.
4. **Read the findings and pick a side.** Every finding names the operation, the JSON location and a stable rule ID (here response-null-not-allowed), and carries two fixes: one if the spec is the source of truth, one if the implementation is. Decide per finding, fix that side, and rerun until the report is clean.
5. **Make it automatic.** Paste the instructions paragraph into CLAUDE.md or AGENTS.md so the agent runs the check after touching a route or the spec, install the Claude Code plugin for the PostToolUse reminder hook, and add the CI job that starts the app and runs apidrifter with --fail-on breaking.

## 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

```sh
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 8000
```

## Run apidrifter

```sh
npx -y apidrifter run http://localhost:8000/openapi.json --base-url http://localhost:8000 --format markdown
```

The 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

The real report for the example, which has one deliberate mismatch (path separators shown as >):

```markdown
## 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.

Instructions file (CLAUDE.md, AGENTS.md or equivalent):

```markdown
## 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.
```

CI job (see .github/workflows/apidrifter.yml in the example for the full file):

```yaml
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.

Last reviewed 2026-11-03 against apidrifter 0.1.0. CLI reference: https://apidrifter.com/docs/cli/. All guides: https://apidrifter.com/guides/
