Verify your Fastify app against its OpenAPI spec

Fastify's route schemas do double duty: @fastify/swagger turns them into an OpenAPI document, and fast-json-stringify uses the response schema to serialize replies. That coupling is strong where it applies and absent where it does not. A status code the response schema does not list still goes out, just without serialization or validation, and the document never mentions it. apidrifter sends one request per operation to the running app, checks every response against the document the app serves, and tells you which side to change.

  1. 01 Find the OpenAPI document. Details
  2. 02 Start the Fastify app. Details
  3. 03 Run apidrifter against it. Details
  4. 04 Read the findings and pick a side. Details
  5. 05 Make it automatic. Details

Where the Fastify spec comes from

After app.register(swagger, { openapi: {...} }) and app.ready(), app.swagger() returns the generated document; the example serves it at /openapi.json from a route marked hide: true so it does not document itself. apidrifter can read it from that URL. For a file to diff in CI, the example's npm run spec writes the same document to openapi.json.

JSON Schema examples on params, body and shared schemas are emitted as OpenAPI example values, which apidrifter uses to fill path parameters and bodies. A whole-body examples entry on the body schema is enough to send a POST without a plan file.

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/fastify
npm install
npm start

Run apidrifter

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

The spec argument is the URL the app serves; plain http:// is accepted for localhost only. If an operation is listed under Skipped for missing values, add examples to the route schema or run apidrifter plan, fill the slots, 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

1 breaking, 0 warning, 0 info.
Coverage: 4 of 4 operations observed, 0 observations matched no operation.

### Breaking (1)

- `undocumented-status` at `POST /todos > response 201` (observation 3): status 201 is not documented for "POST /todos"
  - If the spec is the source of truth: Return one of the documented statuses (200) from POST /todos.
  - If the implementation is the source of truth: Add a "201" response under paths["/todos"].post.responses.

The example's create route declares response: { 200: Todo } and the handler calls reply.code(201). Fastify sends the 201 without complaint, with the body serialized by plain JSON.stringify rather than the schema, and the document lists only 200. A generated client has no branch for 201, so the finding is breaking.

Which side is right? 201 Created is the right status for a create, so the implementation is the source of truth and the schema is wrong: change the response key from 200 to 201 in app.js. That also turns Fastify's schema serialization back on for the created todo, which is a second reason to want the schema and the handler to agree. If the team's convention were 200 for everything, the fix would be reply.code(200) instead. Either way, a status the schema does not list is a status Fastify will send unvalidated.

Make it automatic

Generated documents drift less often than hand-written ones, but when they drift it is in the places the generator cannot see: status codes set by hand, replies that bypass the schema, data the schema is looser than. Three pieces make the check 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 route schema 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 (3000).
2. Run `npx -y apidrifter plan http://localhost:3000/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:3000/openapi.json --base-url http://localhost:3000 --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
    - run: npm install
    - name: Start the app
      run: |
        npm start &
        for i in $(seq 1 20); do curl -sf http://localhost:3000/health && break; sleep 0.5; done
    - name: Verify the implementation against the spec
      run: |
        npx -y apidrifter run http://localhost:3000/openapi.json --base-url http://localhost:3000 \
          --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. The example's workflow also has a spec-diff job: it regenerates openapi.json with npm run spec, fails if the committed snapshot is stale, and runs apidrifter/action@v1 against the base branch so a breaking schema change is flagged on the pull request.

Frequently asked questions

Fastify serializes responses from the schema, so how can a response not match it?
Serialization applies only to status codes the response schema lists. A reply.code(201) on a route that documents 200, an error thrown before the handler, or a route with no response schema at all all go out as plain JSON. Fastify also strips undeclared properties rather than reporting them, which hides one kind of drift and says nothing about types or nulls the schema gets wrong.
Where do the example values come from?
From the examples keyword in your route and shared schemas; @fastify/swagger emits the first one as an OpenAPI example and apidrifter picks it up for path parameters and request bodies. Without examples, run apidrifter plan, fill the slots, and pass --plan filled.json.
Can I diff the generated document in CI?
Yes. Commit the output of app.swagger() (npm run spec in the example), fail the build if it is stale, and run apidrifter/action@v1 against the version on the base branch. The live check against the running app is a separate job.

Example: examples/fastify in the repository. Last reviewed against apidrifter 0.1.0.