Qu'est-ce que nestjs-docfy

Une couche d'outillage NestJS qui sort les décorateurs Swagger des contrôleurs, sans perdre le typage ni changer la sortie OpenAPI générée.

Le problème

Les contrôleurs NestJS documentés avec @nestjs/swagger accumulent vite des dizaines de @ApiOperation, @ApiResponse, @ApiBody, et @ApiTags, au point que la vraie logique de la route finit enterrée sous les métadonnées de documentation.

La solution

nestjs-docfy introduit une convention simple : pour chaque *.controller.ts, il y a un *.controller.docs.ts à côté, qui contient toute la documentation. C'est le même schéma que Nest utilise déjà pour *.spec.ts.

  • Aucun changement à la sortie OpenAPI générée.
  • Typage préservé : le fichier compagnon importe la classe du contrôleur.
  • Découverte via require.cache, avant SwaggerModule.createDocument().

Avant et après

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

La découverte de fichier compagnon dépend de require.cache, donc ça ne fonctionne pas à l'exécution avec nest-cli.json configuré avec "webpack": true. Pour ces projets, enregistre plutôt le plugin CLI, puisqu'il corrige ça automatiquement, à la racine, à chaque build.

Quand l'utiliser

C'est adapté quand

  • Ton API a des dizaines d'endpoints et plusieurs réponses par route.
  • Ton équipe traite OpenAPI comme un contrat versionné.
  • Tu veux des garde-fous CI objectifs (couverture minimale, lint de la doc).
AI-first

Le package compagnon docfy-ui affiche la référence API avec un bouton Copy for AI sur chaque endpoint, idéal à coller dans un LLM.