Verify your Hono app against its OpenAPI spec

With @hono/zod-openapi the request and response schemas are Zod objects, and the OpenAPI document is generated from them. The schemas validate requests, but a response is only checked by TypeScript, and TypeScript does not know what is in your database. A value that the store accepts and the enum does not list goes out untouched. 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 Hono 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 Hono spec comes from

The app serves the generated document wherever app.doc() is mounted, /openapi.json in the example, built from the createRoute() definitions and their Zod schemas. apidrifter can read it from that URL. For a file to diff in CI, app.getOpenAPIDocument(config) returns the same document; the example's npm run spec writes it to openapi.json.

Examples on schemas (.openapi({ example })) end up in the document and are what apidrifter uses to fill path parameters and bodies. A whole-body example on the request 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/hono
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 .openapi({ example }) to the 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

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

### Breaking (2)

- `response-enum-violation` at `GET /todos/{id} > response 200 > application/json > /priority` (observation 2): response body at /priority: value "\"urgent\"" is not one of the allowed values
  - If the spec is the source of truth: Return one of the documented values in response body at /priority.
  - If the implementation is the source of truth: Add the returned value to the enum at paths["/todos/{id}"].get.responses["200"].content["application/json"].schema.properties["priority"].

The example's PrioritySchema is z.enum(["low", "medium", "high"]). The store has a todo whose priority is urgent, and the handler returns the row as is; zod-openapi validates the request, not the response. A client generated from the document maps the enum to a closed type, so the row cannot be decoded; that is why the finding is breaking.

Which side is right? If urgent is a real priority the product supports, the schema is wrong: add it to the enum in src/app.ts and the document regenerates with the next start. If it was a typo in a migration or a value the API should never have accepted, the data is wrong, and the handler that let it in needs the same enum on its request side. With a generated document, fixing the spec means fixing the schema the code is built from, so the two sides are never far apart; the decision is still yours.

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: data, side effects, status codes set by hand. 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 Zod 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

The schemas are typed, so why would a Hono response not match the document?
Types describe what the code says it returns, not what the store holds. An enum value that was added to the database but not to the schema, a null in a column the schema calls required, or a status code set by hand all pass the type checker. apidrifter checks the actual bytes against the document the app serves.
Do I need to export the document to a file?
Not for the live check; pass the /openapi.json URL directly. For spec-to-spec diffs in CI you need a file from each side, so the example commits openapi.json from app.getOpenAPIDocument() and fails the build if it is stale.
What if apidrifter skips my POST operation?
It means no example value could be found for the body. Add .openapi({ example: {...} }) to the request schema, or run apidrifter plan, write the body in a filled plan, and pass --plan filled.json. The engine never invents request values.

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