Wat is nestjs-docfy

Een NestJS-toolinglaag die Swagger-decorators uit controllers haalt, zonder typering te verliezen of andere OpenAPI-output te genereren.

Het probleem

NestJS-controllers gedocumenteerd met @nestjs/swagger verzamelen al snel tientallen @ApiOperation-, @ApiResponse-, @ApiBody- en @ApiTags-decorators, tot het punt waarop de echte logica van de route begraven raakt onder documentatiemetadata.

De oplossing

nestjs-docfy introduceert een simpele conventie: naast elke *.controller.ts staat een *.controller.docs.ts met daarin alle documentatie. Hetzelfde patroon dat Nest al gebruikt voor *.spec.ts.

  • Geen enkele wijziging aan de gegenereerde OpenAPI-output.
  • Typering behouden: het companion-bestand importeert de controllerklasse.
  • Discovery via require.cache, vóór SwaggerModule.createDocument().

Voor en na

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

Companion-file discovery hangt af van require.cache, dus werkt het niet tijdens runtime met nest-cli.json geconfigureerd met "webpack": true. Registreer voor die projecten in plaats daarvan de CLI-plugin, want die repareert dit automatisch, bij de bron, bij elke build.

Wanneer je het gebruikt

Goed geschikt wanneer

  • Je API heeft tientallen endpoints en meerdere responses per route.
  • Je team behandelt OpenAPI als een geversioneerd contract.
  • Je wilt objectieve CI-gates (minimale coverage, docs-linting).
AI-first

Het companion-pakket docfy-ui rendert de API-referentie met op elk endpoint een Copy for AI-knop, ideaal om in LLM's te plakken.