Nest Docfy - More than just a Swagger doc

Nest Docfyen

More than just a<br>Swagger doc.<br>nestjs-docfy separates Swagger/OpenAPI documentation from controller logic using a companion file naming convention, the same way Nest already does with *.controller.spec.ts.<br>Get started View on GitHub View on npm<br>Installation<br>npm install nestjs-docfy<br># peer deps<br>npm install @nestjs/common @nestjs/swagger reflect-metadata

Latest release v0.16.1License MIT

Companion file by convention

users.controller.ts → users.controller.docs.ts. The same pattern Nest already uses for *.controller.spec.ts.

CLI with CI gates

check, coverage --min, lint and patch-spec. Fail the build when documentation is missing.

Automatic type inference

Interfaces, class-validator, and @HttpCode() become an OpenAPI schema without extra decorators.

Docfy UI AI-first

A reference UI with a Copy for AI button on every endpoint, ideal for pasting into LLMs.

docfy-ui: an AI-first reference viewer<br>The OpenAPI spec that nestjs-docfy assembles is also what docfy-ui renders, with no separate config and the same source of truth.<br>Copy for AI: a deterministic, LLM-ready summary of the endpoint, not a raw JSON dump with $ref<br>⌘K search across every endpoint, instantly<br>Full request/response detail per endpoint, generated straight from the spec

Built for AI agents, not just humans<br>docfy-mcp exposes your OpenAPI spec as MCP tools, so Claude, Cursor, or any MCP-compatible agent can query your API directly — no copy-pasting JSON into a prompt.

list_endpoints / get_endpoint: browse and inspect any operation, the same normalized shape docfy-ui renders<br>lint_spec: flags missing summaries, descriptions, tags, and error responses before they ship<br>diff_specs: compares two OpenAPI documents and flags breaking vs. informational changes<br>contract_test: validates a live response against its declared schema, from the agent's own tool calls<br>Zero-config against a running NestJS server, or point it at a static spec file<br>claude_desktop_config.json<br>"mcpServers": {<br>"docfy": {<br>"command": "npx",<br>"args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]

Explore docfy-mcp

What it looks like in practice<br>Before: a controller buried in decorators. After: just routes, with the documentation living alongside it, in a companion file.<br>users.controller.ts<br>@WithDocs()<br>@Controller('users')<br>export class UsersController {<br>constructor(private readonly users: UsersService) {}

@Get(':id')<br>findOne(@Param('id') id: string) {<br>return this.users.findOne(id);

users.controller.docs.ts<br>import { docs } from 'nestjs-docfy';<br>import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';<br>import { UsersController } from './users.controller';

docs(UsersController, {<br>classDecorators: [ApiTags('users')],<br>methods: {<br>findOne: [<br>ApiOperation({ summary: 'Get user by id' }),<br>ApiResponse({ status: 200, description: 'OK', type: UserDto }),<br>ApiResponse({ status: 404, description: 'User not found' }),<br>],<br>},<br>});

Boot-time only, zero per-request overheadSame OpenAPI output as inline decoratorsCompanion file convention, like *.spec.ts

No monkey-patching, no runtime proxies<br>Just the right timing and Reflect metadata.<br>01Write the companion file<br>users.controller.docs.ts calls docs(UsersController, { ... }), plain Swagger decorators, just in another file.

02Discovered at boot<br>DocfyModule.forRoot() finds it via naming convention and writes Reflect metadata onto the controller's methods, before SwaggerModule.createDocument() runs.

03Identical OpenAPI output<br>SwaggerModule sees the exact same metadata it would if the decorators were written inline on the controller.

Not a Swagger plugin. The whole toolchain.<br>Most tools stop at decorators. nestjs-docfy ships the CLI, the viewer, and the AI integration your team actually needs to keep documentation honest.

A CLI that gates your CI<br>generate, check, coverage --min, lint, and patch-spec fail the build the moment documentation drifts from code — not months later.

Zero runtime cost, if you want it<br>The webpack CLI plugin computes everything at build time; nothing runs per-request in production.

docfy-ui included, not sold separately<br>A full AI-first reference viewer ships with the library — no extra account, no separate pricing tier.

Agents as first-class citizens<br>docfy-mcp exposes the same spec to Claude, Cursor, and any MCP client — your API becomes queryable, not just readable.

Works with whatever NestJS layout you already have<br>Simple projects, Nx workspaces, and Nest CLI monorepos are all auto-detected — no config file to write by hand.

One command from zero to fully wired<br>nestjs-docfy init wires the module, decorates every controller, and generates the docs — in one shot.

See the full docs