Mehr als nur
Swagger-Docs.

nestjs-docfy trennt Swagger-/OpenAPI-Dokumentation von der Controller-Logik über eine Companion-File-Namenskonvention, genauso wie Nest es schon macht mit *.controller.spec.ts.

Loslegen Auf GitHub ansehen Auf npm ansehen

Installation

npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadata

Neuestes Release v0.18.1Lizenz MIT

Companion-Datei per Konvention

users.controller.ts → users.controller.docs.ts. Dasselbe Muster, das Nest schon für *.controller.spec.ts nutzt.

CLI mit CI-Gates

check, coverage --min, lint und patch-spec. Lässt den Build scheitern, wenn Dokumentation fehlt.

Automatische Typableitung

Interfaces, class-validator und @HttpCode() werden ohne zusätzliche Decorators zu einem OpenAPI-Schema.

Docfy UI AI-first

Eine Referenz-UI mit einem Copy-for-AI-Button auf jedem Endpunkt, ideal zum Einfügen in LLMs.

docfy-ui: ein AI-first Referenz-Viewer

Die OpenAPI-Spec, die nestjs-docfy zusammenstellt, ist dieselbe, die docfy-ui rendert, ohne separate Konfiguration und mit derselben Quelle der Wahrheit.

Copy for AI: eine deterministische, LLM-fertige Zusammenfassung des Endpunkts, kein roher JSON-Dump mit $ref
⌘K-Suche über jeden Endpunkt, sofort
Vollständige Request-/Response-Details pro Endpunkt, direkt aus der Spec erzeugt

docfy-ui detalhe de endpoint com Copy for AI

Für KI-Agenten gebaut, nicht nur für Menschen

docfy-mcp stellt deine OpenAPI-Spec als MCP-Tools bereit, sodass Claude, Cursor oder jeder MCP-kompatible Agent deine API direkt abfragen kann, ohne JSON in einen Prompt zu kopieren.

list_endpoints / get_endpoint: jede Operation durchsuchen und untersuchen, in derselben normalisierten Form, die docfy-ui rendert
lint_spec: markiert fehlende Summaries, Beschreibungen, Tags und Fehlerantworten, bevor sie live gehen
diff_specs: vergleicht zwei OpenAPI-Dokumente und markiert Breaking- vs. informative Änderungen
contract_test: validiert eine echte Antwort gegen ihr deklariertes Schema, direkt aus den Tool-Aufrufen des Agenten
Zero-Config gegen einen laufenden NestJS-Server, oder auf eine statische Spec-Datei zeigen

claude_desktop_config.json

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

docfy-mcp entdecken

So sieht es in der Praxis aus

Vorher: ein Controller, begraben unter Decorators. Nachher: nur Routen, mit der Dokumentation direkt daneben, in einer Companion-Datei.

users.controller.ts

@WithDocs()
@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

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

users.controller.docs.ts

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' }),
    ],
  },
});

Nur zur Boot-Zeit, kein Overhead pro RequestDieselbe OpenAPI-Ausgabe wie Inline-DecoratorsCompanion-File-Konvention, wie *.spec.ts

Kein Monkey-Patching, keine Runtime-Proxys

Nur das richtige Timing und Reflect-Metadaten.

Companion-Datei schreiben

users.controller.docs.ts ruft docs(UsersController, { ... }) auf, ganz normale Swagger-Decorators, nur in einer anderen Datei.

Beim Boot erkannt

DocfyModule.forRoot() findet sie über die Namenskonvention und schreibt Reflect-Metadaten auf die Methoden des Controllers, bevor SwaggerModule.createDocument() läuft.

Identische OpenAPI-Ausgabe

SwaggerModule sieht genau dieselben Metadaten, die es sähe, wären die Decorators direkt inline auf dem Controller geschrieben.

Kein Swagger-Plugin. Die ganze Toolchain.

Die meisten Tools hören bei Decorators auf. nestjs-docfy liefert die CLI, den Viewer und die KI-Integration, die dein Team wirklich braucht, um Dokumentation ehrlich zu halten.

Eine CLI, die deine CI absichert

generate, check, coverage --min, lint und patch-spec lassen den Build fehlschlagen, sobald Dokumentation vom Code abweicht, nicht erst Monate später.

Null Laufzeitkosten, wenn du willst

Das Webpack-CLI-Plugin berechnet alles zur Build-Zeit; in Produktion läuft nichts pro Request.

docfy-ui inklusive, nicht separat verkauft

Ein vollständiger AI-first-Referenzviewer ist Teil der Bibliothek: kein zusätzliches Konto, kein separater Tarif.

Agenten als Bürger erster Klasse

docfy-mcp stellt dieselbe Spec Claude, Cursor und jedem MCP-Client bereit, deine API wird abfragbar, nicht nur lesbar.

Funktioniert mit dem NestJS-Layout, das du schon hast

Einfache Projekte, Nx-Workspaces und Nest-CLI-Monorepos werden alle automatisch erkannt, keine Konfigurationsdatei von Hand.

Ein Befehl von null zur vollständigen Verdrahtung

nestjs-docfy init verdrahtet das Modul, dekoriert jeden Controller und generiert die Docs, alles in einem Schritt.

Zur vollständigen Dokumentation

Mehr als nurSwagger-Docs.