Verify your Express app against its OpenAPI spec
Express does not know what your API looks like; the OpenAPI document is a separate file that someone wrote by hand and that nobody is forced to update when a handler changes. That is the most common shape of API drift, and the one our survey of public APIs found most often: the implementation moved, the document did not. apidrifter sends one request per operation to the running app, checks every response against the document, and tells you which side to change.
- 01 Find the OpenAPI document. Details
- 02 Start the Express app. Details
- 03 Run apidrifter against it. Details
- 04 Read the findings and pick a side. Details
- 05 Make it automatic. Details
Where the Express spec comes from
The document is a file in the repository, typically openapi.yaml or openapi.json next to the server code, maintained by hand or by a doc generator such as swagger-jsdoc. apidrifter takes the file path directly. The example keeps a strict document: its Todo schema has additionalProperties: false, so an extra field in a response is a breaking finding rather than an info one.
If your Express project generates the document from JSDoc comments, run the generator first and point apidrifter at its output file; the check is the same.
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/express
npm install
npm startRun apidrifter
npx -y apidrifter run openapi.yaml --base-url http://localhost:3000 --format markdownPath parameters and request bodies get their values from the example fields in the document, so the example runs without a plan file. If your document has no examples, run apidrifter plan openapi.yaml --out plan.json, fill the slots it lists, and add --plan filled.json; the engine never invents values.
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
3 breaking, 0 warning, 0 info.
Coverage: 4 of 4 operations observed, 0 observations matched no operation.
### Breaking (3)
- `response-forbidden-property` at `GET /todos/{id} > response 200 > application/json > /ownerId` (observation 2): response body at /ownerId: property "ownerId" is not allowed
- If the spec is the source of truth: Stop returning "ownerId" from GET /todos/{id}; the spec forbids unknown properties here.
- If the implementation is the source of truth: Add "ownerId" to paths["/todos/{id}"].get.responses["200"].content["application/json"].schema.properties or allow additionalProperties.The example's rows carry an ownerId that the hand-written Todo schema never declared. Because the schema says additionalProperties: false, the extra field is a breaking finding: a strictly decoding client rejects the whole response. The same mismatch on a schema without that line would be response-undocumented-property, an info finding, which the example's apidrifter.config.json raises to a warning so it still shows up in CI.
Which side is right? If ownerId is meant to be public, the document is wrong: add it to components.schemas.Todo.properties and to required, since the server always sets it. If it leaked out of the store by accident, the implementation is wrong: strip it before res.json(). The fix nobody should pick is adding additionalProperties: true to make the report quiet; that makes the document say less, not more.
Make it automatic
With a hand-written document the check matters most, because nothing else ties the two together. 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 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 openapi.yaml --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 openapi.yaml --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 openapi.yaml --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 openapi.yaml or a file under routes, controllers, handlers or api. The example's workflow also has a spec-diff job that runs apidrifter/action@v1 on openapi.yaml against the base branch, so a breaking edit to the document is flagged on the pull request even when the server is untouched.
Frequently asked questions
- My Express project has no OpenAPI document. Where do I start?
- Write one for the operations you have, with an example value for every path parameter and request body, and run apidrifter against it. The findings tell you where the document is wrong, with the spec-side fix spelled out, so the first few runs double as a way to get the document right.
- Does apidrifter need additionalProperties: false to catch extra fields?
- No. Without it an extra field is reported as response-undocumented-property at info severity. With it the finding is response-forbidden-property at breaking severity, because strict clients reject the response. Use apidrifter.config.json to raise the info rule to warning if you want extra fields visible in CI without tightening every schema.
- Can the same check run against staging?
- Yes, over https://. Plain http:// is accepted for localhost only. Pass --bearer-env VAR for a token kept in an environment variable; it never appears in output.
Example: examples/express in the repository. Last reviewed against apidrifter 0.1.0.