DEV Community: Marvin Rocha

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

Marvin Rocha — Sun, 02 Aug 2026 00:15:01 +0000

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.

Nestjs Docfy v0.7: export without a running server, and an MCP server for your API docs

Marvin Rocha — Wed, 29 Jul 2026 02:38:45 +0000

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, plus docfy-ui, an AI-first reference UI with a "Copy for AI" button on every endpoint. Two things kept coming up since: you shouldn't need Postgres running just to read your own API's docs, and there was no way for an AI agent to query the API directly without a human pasting Swagger UI into the chat.

v0.7 closes both, and ships a new companion project to go with it: docfy-mcp.

`export`: your OpenAPI document without `.listen()`

SwaggerModule.createDocument() needs a fully-booted Nest app to introspect routes and DTOs — but "fully booted" doesn't mean "listening on a port," and in most setups it doesn't mean "infrastructure running" either. Most TypeOrmModule/ioredis/kafkajs clients connect lazily, so the DI container resolves fine without a live database or broker.

nestjs-docfy export takes advantage of that:

npx nestjs-docfy export --entry docfy-export.ts --out openapi.json

The entry file is the same handful of lines your main.ts already has, minus .listen():

// docfy-export.ts
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

export default async function () {
  const app = await NestFactory.create(AppModule, { logger: false });
  const config = new DocumentBuilder().setTitle('My API').setVersion('1.0.0').build();
  const document = SwaggerModule.createDocument(app, config);
  return { app, document }; // `app` gets closed for you afterward
}

I tested this against a real multi-service NestJS monorepo — Postgres, Redis, Kafka, Zookeeper, all stopped — and export still produced the full document, cold, on the first try.

One thing worth knowing: this doesn't fix a provider with a genuinely eager, hard-failing connection in its constructor or onModuleInit. export only avoids the one thing NestJS itself doesn't actually need — an open port. If your app blocks bootstrap on a live DB connection today, it still will under export.

Also: informational output goes to stderr, not stdout, specifically so export --entry x.ts > openapi.json stays safe to pipe.

docfy-mcp: your API as MCP tools

The AI-first framing on docfy-ui was always about a human copying text into a chat. docfy-mcp removes the copying:

npx docfy-mcp --url http://localhost:3000/api-json

Two tools:

list_endpoints — method, path, and summary for everything in the catalog, with an optional filter
get_endpoint — full Purpose/Request/Parameters/Validation/Success Response/Error Responses text for one endpoint, given method + path

{
  "mcpServers": {
    "docfy": {
      "command": "npx",
      "args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/api-json"]
    }
  }
}

and an agent like Claude Code or Cursor can call get_endpoint directly instead of guessing from a stale comment.

One gotcha, and the reason --url doesn't just delegate to swagger-parser's own HTTP resolver: swagger-parser's SSRF guard blocks localhost/private addresses by default. That's exactly the case here — pointing at a local NestJS dev server — so docfy-mcp fetches the spec itself instead. If --url 404s (the OpenAPI JSON path isn't a fixed convention — /api-json, /docs-json, /swagger-json, whatever your project chose), it probes a handful of common sibling paths on the same origin and suggests one, instead of leaving you to guess blind. For specs behind auth, --header "Authorization: Bearer xyz" is repeatable.

Also new: "Copy MCP Reference" in docfy-ui

Alongside "Copy for AI" and "Copy OpenAPI," every endpoint now has a Copy MCP Reference button — copies METHOD /path plus the page's canonical URL. Paste it into a chat with an MCP-connected agent and it has exactly what get_endpoint needs; open the URL and you're looking at that endpoint's docs directly. Same idea as Figma's "copy link to selection."

One bug fix worth mentioning

While testing all this against a real project, I found that a plain boolean field on a response DTO was rendering as oneOf: [{type:"boolean"}, {type:"boolean"}] instead of {type:"boolean"}. TypeScript represents the boolean keyword type as a union of the literal types true | false internally — confirmed via ts-morph's Type.isUnion() returning true for a plain success: boolean field — and the schema-inference code wasn't collapsing the two identical branches. Fixed in 0.6.3.

Nothing else changes: same install, same DocfyModule.forRoot(), same *.controller.docs.ts convention. docfy-mcp and the export command are additive — if you never touch them, nothing about your existing setup moves.

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 reading your own API's docs required infra you didn't want to boot, or your agent kept guessing your API's shape, this release is for you.

nestjs-docfy just got Fastify support (and a docs site to go with it)

Marvin Rocha — Fri, 24 Jul 2026 03:44:29 +0000

A couple of weeks ago I shared nestjs-docfy here, a library that moves Swagger decorators out of NestJS controllers into companion *.controller.docs.ts files, plus docfy-ui, an AI-first reference UI with a "Copy for AI" button on every endpoint. The response was great, and two specific limitations came up repeatedly: Fastify wasn't supported, and reloading a deep-linked endpoint page in docfy-ui broke. I said I'd rather flag those than have people find out mid-deploy.

0.4.0 closes both.

Fastify support for docfy-ui

DocfyUiModule.setup() was Express-only. It now works on Fastify apps too, through a scoped @fastify/static registration — the same package @nestjs/swagger itself already relies on for Fastify's Swagger UI support:

npm install @fastify/static

import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { DocfyUiModule } from 'nestjs-docfy';

const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());

DocfyUiModule.setup('/docs', app);

await app.listen(3000);

Same call, same "Copy for AI" button, same zero-config /api-json discovery — just works on either adapter now.

One Fastify-specific thing worth knowing: SwaggerModule.setup() registers its own /api-json route too. On Express, whichever route wins is whoever registered first, silently. On Fastify, registering the same route twice throws FST_ERR_DUPLICATED_ROUTE at startup instead — order alone won't save you. If you're combining Fastify with a static, pre-patched spec (staticSpecPath, for webpack: true builds), point SwaggerModule.setup() at a different jsonDocumentUrl so it doesn't also claim /api-json.

Deep-link reload, fixed

If you mounted the UI outside the root — DocfyUiModule.setup('/docs', app) — and reloaded a specific endpoint's page directly by URL instead of navigating there client-side, you'd get a 404. Routing inside DocfyUiModule was reworked to handle the SPA fallback properly for both adapters, so a hard reload on a deep route now resolves the same as client-side navigation.

Also new: a proper docs site

The README carried the full API reference on its own for a while, which worked but wasn't great for actually browsing. There's now a dedicated docs site — same content, organized as an actual reference with search, instead of one long scroll.

🔗 nestdocfy.com

Nothing else changes: same install, same DocfyUiModule.setup('/docs', app), same zero backend coupling — it still just consumes an OpenAPI 3.0/3.1 document, so it works with any server that exposes one, not just NestJS.

npm install nestjs-docfy
npm install docfy-ui

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

If Fastify or the deep-link bug was the thing holding you back, this release should clear it.

Nestjs — Stop burning AI credits to write Swagger docs, let the CLI do it!

Marvin Rocha — Thu, 11 Jun 2026 12:46:15 +0000

Last Sunday I shared nestjs-docfy, a small library to move Swagger decorators out of NestJS controllers into companion *.controller.docs.ts files. The reception was better than I expected, and a lot of the feedback pointed in the same direction: the separation is nice, but writing those docs files by hand is still tedious.

So I spent some time on that, and there's quite a bit new in this release.

A CLI that writes the boilerplate for you

The biggest addition is a generate command that reads your project with static analysis (no code execution, no ts-node overhead) and produces a pre-filled docs file for every controller:

npx nestjs-docfy generate

The generated file comes with inferred summaries, response types, and common error responses already in place. You edit from there instead of starting from scratch.

It's idempotent by default, running it again won't touch files that already exist. When you add a new endpoint and want to merge only the new method block without losing your existing edits:

npx nestjs-docfy generate --force

The CLI auto-detects your project layout, so monorepos (Nx, Nest CLI, generic packages/ or apps/ structures) work without any configuration.

There's also a --dry-run flag if you want to preview output before writing anything to disk.

A check command for CI

The other side of the workflow is keeping docs in sync as the codebase evolves. The check command exits with code 1 if any controller has undocumented methods or no companion file at all:

npx nestjs-docfy check

Output looks like this when something is out of sync:

✖ UsersController, undocumented methods: updateProfile, deleteAccount
  → run nestjs-docfy generate --force to merge new methods

✖ 2 controller(s) out of sync.

Drop it into your pipeline and docs drift gets caught before it reaches main.

Type-safe method keys

The docs() function now enforces that every key in config.methods actually exists on the controller class. Typos are a compile error, not a silent runtime warning:

docs(UsersController, {
  methods: {
    findAll: [...],    // ✔ exists on UsersController
    typoMethod: [...], // ✖ TypeScript error
  },
});

Interface-typed DTOs just work

This one came up a lot. If your response or body type is a TypeScript interface, Swagger can't use it as a type: value because interfaces are erased at runtime. Previously you had to convert them to classes or write the schema by hand.

Now the CLI detects this automatically and generates an inline schema: object instead:

// Your existing interface — no changes needed
export interface RegisterResponseDto {
  success: boolean;
  message: string | null;
}

Generated output:

ApiResponse({
  status: 201,
  description: 'Created',
  schema: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      message: { type: 'string', nullable: true },
    },
    required: ['success'],
  },
}),

Supports primitives, nullable unions, arrays, nested interfaces, and optional properties.

class-validator inference

If a DTO uses class-validator decorators and doesn't already have @ApiProperty on its properties, the CLI infers the full JSON Schema from the validators — no manual annotation needed:

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;

  @IsOptional()
  @IsString()
  bio?: string;
}

Generated output:

ApiBody({
  schema: {
    type: 'object',
    properties: {
      name:  { type: 'string', minLength: 2 },
      email: { type: 'string', format: 'email' },
      bio:   { type: 'string' },
    },
    required: ['name', 'email'],
  },
}),

If any property already has @ApiProperty, inference is skipped entirely and type: ClassName is used instead, existing annotations are never overwritten.

@HttpCode() awareness

The CLI reads @HttpCode() on route handlers and uses the correct status code in the generated ApiResponse. A @Post with @HttpCode(204) gets status: 204, not the default 201.

The core idea is still the same — controllers express behavior, docs files express documentation, but now the friction of setting that up and keeping it current is mostly gone.

🔗 nestjs-docfy on GitHub · 📦 npm package

If you were holding off because of the manual setup, this release should make it a lot more practical.

NestJS controllers drowning in Swagger decorators? I built a small fix!

Marvin Rocha — Mon, 08 Jun 2026 16:56:57 +0000

I want to share something I've been thinking about for a while while working with NestJS, and a small library I put together to deal with it. Not a revolutionary idea, just something that bothered me enough to actually do something about it.

The thing that kept bothering me

Every time I documented an endpoint, my controller went from something readable to something like this:

@ApiTags('users')
@Controller('users')
export class UsersController {
  @Post()
  @ApiOperation({ summary: 'Create a user' })
  @ApiBody({ type: CreateUserDto })
  @ApiResponse({ status: 201, type: UserEntity })
  @ApiResponse({ status: 400, description: 'Invalid input' })
  create(@Body() dto: CreateUserDto): Promise<UserEntity> {
    return this.usersService.create(dto);
  }
  // ... imagine 4 more endpoints like this
}

The actual routing logi, the part I care about, gets buried under documentation metadata. They're two different concerns sharing the same file, and it starts to feel noisy.

We already separate tests into *.spec.ts files. It felt weird that documentation was treated differently.

What I tried

I built nestjs-docfy, a small module that moves Swagger decorators to a companion file using a *.controller.docs.ts naming convention. The controller stays focused on routing, and the docs file handles everything OpenAPI-related.

users.controller.ts after

@WithDocs()
@Controller('users')
export class UsersController {
  @Post()
  create(@Body() dto: CreateUserDto): Promise<UserEntity> {
    return this.usersService.create(dto);
  }
}

users.controller.docs.ts

import { docs } from 'nestjs-docfy';

docs(UsersController, {
  classDecorators: [ApiTags('users')],
  methods: {
    create: [
      ApiOperation({ summary: 'Create a user' }),
      ApiBody({ type: CreateUserDto }),
      ApiResponse({ status: HttpStatus.CREATED, type: UserEntity }),
      ApiResponse({ status: HttpStatus.BAD_REQUEST, description: 'Invalid input' }),
    ],
  },
});

How it works

You add DocfyModule.forRoot() to your AppModule, that's the only required change. During NestFactory.create(), the module resolves companion files for controllers marked with @WithDocs() and applies the metadata via Reflect. Since this happens before SwaggerModule.createDocument() runs, the Swagger generator sees everything exactly as if the decorators were inline.

No changes to your bootstrap flow, no magic at runtime.

It's a small thing, but it made my controllers a lot easier to read. If your team deals with the same noise, it might be worth a look.