Was ist nestjs-docfy

Eine NestJS-Tooling-Schicht, die Swagger-Decorators aus Controllern herauslöst, ohne Typisierung zu verlieren oder eine andere OpenAPI-Ausgabe zu erzeugen.

Das Problem

NestJS-Controller, die mit @nestjs/swagger dokumentiert werden, sammeln schnell Dutzende von @ApiOperation, @ApiResponse, @ApiBody und @ApiTags an, bis die eigentliche Logik der Route unter Dokumentations-Metadaten begraben ist.

Die Lösung

nestjs-docfy führt eine einfache Konvention ein: zu jeder *.controller.ts gibt es eine *.controller.docs.ts daneben, die die gesamte Dokumentation enthält. Dasselbe Muster, das Nest schon für *.spec.ts nutzt.

  • Null Änderung an der generierten OpenAPI-Ausgabe.
  • Typisierung bleibt erhalten: Die Companion-Datei importiert die Controller-Klasse.
  • Erkennung über require.cache, vor SwaggerModule.createDocument().

Vorher und nachher

users.controller.ts
@WithDocs()
@Controller('users')
export class UsersController {
  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.users.findOne(id);
  }
}
users.controller.docs.ts
docs(UsersController, {
  classDecorators: [ApiTags('Users')],
  methods: {
    findOne: [
      ApiParam({ name: 'id', type: String }),
      ApiOperation({ summary: 'Get user by id' }),
      ApiResponse({ status: 200, type: UserDto }),
      ApiResponse({ status: 404, description: 'User not found' }),
    ],
  },
});
webpack: true

Die Erkennung der Companion-Datei hängt von require.cache ab, funktioniert also zur Laufzeit nicht, wenn nest-cli.json mit "webpack": true konfiguriert ist. Registrier für solche Projekte stattdessen das CLI-Plugin, das behebt das automatisch, an der Wurzel, bei jedem Build.

Wann man es einsetzt

Gut geeignet, wenn

  • Deine API hat Dutzende Endpunkte und mehrere Responses pro Route.
  • Dein Team behandelt OpenAPI als versionierten Vertrag.
  • Du willst objektive CI-Gates (Mindest-Coverage, Docs-Linting).
AI-first

Das Begleitpaket docfy-ui rendert die API-Referenz mit einem Copy for AI-Button auf jedem Endpunkt, ideal zum Einfügen in LLMs.