---
title: "Verify your Express app against its OpenAPI spec"
description: "Express has no built-in spec, so the OpenAPI document is hand-written and drifts. How to run apidrifter against the app, read a real finding, and automate it."
date: 2026-11-03
author: API Drifter
canonical: https://apidrifter.com/guides/express/
example: https://github.com/apidrifter/apidrifter/tree/main/examples/express
license: Apache-2.0
---

# Verify your Express app against its OpenAPI spec

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

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.

## Steps

1. **Find the OpenAPI document.** 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.
2. **Start the Express app.** Start the service locally and note its port; the example listens on 3000. apidrifter accepts plain http:// for localhost only.
3. **Run apidrifter against it.** Run npx -y apidrifter run openapi.yaml --base-url http://localhost:3000 --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-forbidden-property), 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 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

```sh
git clone https://github.com/apidrifter/apidrifter && cd apidrifter/examples/express
npm install
npm start
```

## Run apidrifter

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

Path 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

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

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

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

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

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

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