Meer dan alleen een
Swagger-doc.
nestjs-docfy scheidt Swagger/OpenAPI-documentatie van controllerlogica via een companion-bestandsconventie, op dezelfde manier waarop Nest dat al doet met *.controller.spec.ts.
npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadatadocfy-ui: een AI-first referentieviewer
De OpenAPI-spec die nestjs-docfy opbouwt is ook wat docfy-ui rendert, zonder aparte configuratie en met dezelfde single source of truth.
- Copy for AI: een deterministische, LLM-klare samenvatting van het endpoint, geen ruwe JSON-dump met $ref
- ⌘K-zoeken door elk endpoint, direct
- Volledig request-/responsedetail per endpoint, rechtstreeks uit de spec gegenereerd
Gebouwd voor AI-agents, niet alleen voor mensen
docfy-mcp stelt je OpenAPI-spec beschikbaar als MCP-tools, zodat Claude, Cursor of elke MCP-compatibele agent je API direct kan bevragen, zonder JSON te plakken in een prompt.
- list_endpoints / get_endpoint: blader door en inspecteer elke operatie, in dezelfde genormaliseerde vorm die docfy-ui rendert
- lint_spec: signaleert ontbrekende summaries, beschrijvingen, tags en foutresponses voordat ze live gaan
- diff_specs: vergelijkt twee OpenAPI-documenten en signaleert breaking vs. informatieve wijzigingen
- contract_test: valideert een live response tegen het gedeclareerde schema, rechtstreeks vanuit de tool calls van de agent zelf
- Zero-config tegen een draaiende NestJS-server, of wijs naar een statisch specbestand
{
"mcpServers": {
"docfy": {
"command": "npx",
"args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
}
}
}Hoe het er in de praktijk uitziet
Voor: een controller bedolven onder decorators. Na: alleen routes, met de documentatie ernaast, in een companion-bestand.
@WithDocs()
@Controller('users')
export class UsersController {
constructor(private readonly users: UsersService) {}
@Get(':id')
findOne(@Param('id') id: string) {
return this.users.findOne(id);
}
}import { docs } from 'nestjs-docfy';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UsersController } from './users.controller';
docs(UsersController, {
classDecorators: [ApiTags('users')],
methods: {
findOne: [
ApiOperation({ summary: 'Get user by id' }),
ApiResponse({ status: 200, description: 'OK', type: UserDto }),
ApiResponse({ status: 404, description: 'User not found' }),
],
},
});Geen monkey-patching, geen runtime proxies
Gewoon de juiste timing en Reflect-metadata.
Schrijf het companion-bestand
users.controller.docs.ts roept docs(UsersController, { ... }) aan, gewone Swagger-decorators, alleen in een ander bestand.
Ontdekt bij het opstarten
DocfyModule.forRoot() vindt het via naamgevingsconventie en schrijft Reflect-metadata op de methoden van de controller, vóórdat SwaggerModule.createDocument() draait.
Identieke OpenAPI-output
SwaggerModule ziet exact dezelfde metadata die het zou zien als de decorators inline op de controller stonden.
Geen Swagger-plugin. De hele toolchain.
De meeste tools stoppen bij decorators. nestjs-docfy levert de CLI, de viewer en de AI-integratie die jouw team echt nodig heeft om documentatie eerlijk te houden.
Een CLI die je CI bewaakt
generate, check, coverage --min, lint en patch-spec laten de build falen zodra documentatie afwijkt van code, niet pas maanden later.
Nul runtime-kosten, als je dat wilt
De webpack CLI-plugin berekent alles tijdens de build; niets draait per request in productie.
docfy-ui inbegrepen, niet apart verkocht
Een volledige AI-first referentieviewer wordt meegeleverd met de library, zonder extra account en zonder apart abonnement.
Agents als eersteklas burgers
docfy-mcp stelt dezelfde spec beschikbaar aan Claude, Cursor en elke MCP-client: je API wordt bevraagbaar, niet alleen leesbaar.
Werkt met de NestJS-indeling die je al hebt
Simpele projecten, Nx-workspaces en Nest CLI-monorepo's worden allemaal automatisch gedetecteerd, zonder configbestand om met de hand te schrijven.
Eén commando van nul naar volledig aangesloten
nestjs-docfy init verbindt de module, decoreert elke controller en genereert de docs, allemaal in één keer.