---
title: "Verify your NestJS app against its OpenAPI spec"
description: "@nestjs/swagger generates the document from decorators. 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/nestjs/
example: https://github.com/apidrifter/apidrifter/tree/main/examples/nestjs
license: Apache-2.0
---

# Verify your NestJS app against its OpenAPI spec

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

In NestJS the OpenAPI document comes from decorators: @ApiProperty on DTOs, @ApiResponse and @ApiParam on controller methods. Decorators describe; they do not enforce. A DTO used as a response type is never validated on the way out, so whatever the service returns is what the client gets, and @ApiProperty marks a property required unless told otherwise. 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.

## Steps

1. **Find the OpenAPI document.** SwaggerModule.createDocument(app, config) builds the document from the decorators; SwaggerModule.setup() serves it, in the example at /openapi.json with the UI at /docs. apidrifter can read it from that URL. For a file to diff in CI, the example's npm run spec creates the app without listening, prints the document, and exits.
2. **Start the NestJS 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 http://localhost:3000/openapi.json --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-missing-required-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 NestJS spec comes from

SwaggerModule.createDocument(app, config) builds the document from the decorators; SwaggerModule.setup() serves it, in the example at /openapi.json with the UI at /docs. apidrifter can read it from that URL. For a file to diff in CI, the example's npm run spec creates the app without listening, prints the document, and exits.

example values on @ApiProperty, @ApiParam and @ApiBody end up in the document and are what apidrifter uses to fill path parameters and bodies. An examples entry on @ApiBody is enough to send a POST without a plan file.

## Start the app

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

## Run apidrifter

```sh
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 example values to the decorators or run apidrifter plan, fill the slots, 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-missing-required-property` at `GET /todos/{id} > response 200 > application/json > /dueDate` (observation 2): response body at /dueDate: required property "dueDate" is missing
  - If the spec is the source of truth: Include "dueDate" in the 200 response of GET /todos/{id}.
  - If the implementation is the source of truth: Remove "dueDate" from required at paths["/todos/{id}"].get.responses["200"].content["application/json"].schema.
```

The example's TodoDto has @ApiProperty() on dueDate, which makes it required in the document. The service only sets dueDate when it has one, so the second todo goes out without it. A client generated from the document treats the field as non-optional and fails on that row; that is why the finding is breaking.

Which side is right? A todo without a due date is a legitimate state, so the implementation is the source of truth and the DTO is wrong: change the decorator to @ApiPropertyOptional() (or @ApiProperty({ required: false })) in src/todo.dto.ts and the document regenerates with dueDate out of required. If the product rule were that every todo has a due date, the service would be wrong instead, and create() should refuse a missing one. Nest does not set additionalProperties: false, so the reverse mistake, a field the service returns that the DTO lacks, is only an info finding; the example's apidrifter.config.json raises it to a warning.

## Make it automatic

Decorator-generated documents drift in the gap between what a decorator says and what a service does. Three pieces make the check 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 controller or DTO 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.
```

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 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 (Nest's *.controller.ts files usually live in feature directories; 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 npm run spec, fails if the committed snapshot is stale, and runs apidrifter/action@v1 against the base branch so a breaking DTO change is flagged on the pull request.

## Frequently asked questions

**Does NestJS validate responses against the DTOs?**

No. ValidationPipe validates incoming bodies against class-validator rules; response DTOs are only used to generate the document and for TypeScript. Whatever the service returns is sent. apidrifter checks the sent bytes against the document, which is the only place the two meet.

**How do I get the document as a file for CI?**

Create the app with NestFactory.create, call app.init(), print SwaggerModule.createDocument(app, config) and exit, as the example's src/export-spec.ts does. Commit the file, fail the build when it is stale, and diff it against the base branch with apidrifter/action@v1.

**Why is a missing field breaking but an extra field only info?**

A client generated from the document treats a required field as always present, so a response without it fails to decode. An extra field on a schema that allows additional properties is ignored by most clients, so it is reported at info severity; raise response-undocumented-property to warning in apidrifter.config.json if you want it in CI.

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