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.13.0Lizenz 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

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.

Mehr als nurSwagger-Docs.