nestjs-docfy: mock servers, contract testing, and a much sharper MCP server

A few weeks ago I shared nestjs-docfy here — a library that moves Swagger decorators out of NestJS controllers into companion *.controller.docs.ts files, docfy-ui as an AI-first reference UI, and docfy-mcp exposing your API catalog to coding agents via list_endpoints/get_endpoint.

Since then the CLI grew a full local dev workflow around the spec itself, and docfy-mcp went from "read the docs" to "verify the API is telling the truth."

docfy mock: a server without the server

\shell
npx nestjs-docfy mock --spec openapi.json --port 4010
\\

Spins up a throwaway HTTP server straight from your OpenAPI document — every path returns a schema-shaped response. Useful for frontend work against an API that isn't built yet, or for pointing an agent at something real instead of a static spec file.

docfy test: contract testing off the spec

\shell
npx nestjs-docfy test --spec openapi.json --base-url http://localhost:3000
\\

Fires a real request at every documented endpoint and validates the live response against its declared schema. Catches the exact failure mode API docs are famous for: the code moved on, the docs didn't. CI-friendly, non-zero exit on drift.

docfy init: zero to configured

\shell
npx nestjs-docfy init
\\

One command, scaffolds the docfy-export.ts entry file and wires DocfyModule.forRoot() for you. No more copy-pasting from the README.

--link-controller: less boilerplate

\shell
npx nestjs-docfy generate --link-controller
\\

Auto-inserts @WithDocs() into the controller so newly generated .controller.docs.ts files are actually wired in — one less manual step per endpoint.

Breaking changes, surfaced in the PR itself

docfy-pr-check-reusable.yml now runs a spec diff and posts breaking vs. informational field changes as a PR comment. You see the blast radius of an API change before merge, not after a consumer files a bug.

docfy-mcp: from lookup to verification

The MCP server picked up three tools that turn it from a reference into an actual QA loop for agents:

• lint_spec — flags spec-quality issues: missing summary/description, missing tags, undocumented 4xx/5xx, duplicate operation IDs
• diff_specs — compares the loaded catalog against another spec (a file, a URL, a previous git tag) and reports breaking vs. informational changes
• contract_test — fires real requests at a running server and validates responses against the schema, with a filter and repeatable --header for auth, plus a timeout and response-size cap so a runaway endpoint can't hang the agent's turn

Combined with list_endpoints/get_endpoint, an agent implementing a client can now lint the spec it's about to consume, diff it against what it saw last session, and contract-test its own integration — all inside the editor, no browser round-trip.

Security hardening shipped alongside: contract_test requests are capped and time-boxed, and hitting arbitrary servers is opt-in via an allowlist rather than default-open.

Docs, now in 10 languages

nestdocfy.com is fully localized — EN, PT, ES, DE, FR, IT, NL, PL, ZH, JA — same content, same nav, picked up automatically from the browser's locale.

---

Nothing about the existing setup changes — same DocfyModule.forRoot(), same *.controller.docs.ts convention. Everything above is additive.

\shell
npm install nestjs-docfy
npx docfy-mcp --url <your-openapi-json>
\\

🔗 nestjs-docfy on GitHub · 📦 nestjs-docfy on npm · 📦 docfy-mcp on npm · 📖 docs

If your API docs drift from reality, or your agent is still guessing your API's shape from stale comments, this release closes both gaps.