Bien plus qu'une
doc Swagger.

nestjs-docfy sépare la documentation Swagger/OpenAPI de la logique des contrôleurs grâce à une convention de fichier compagnon, de la même façon que Nest le fait déjà avec *.controller.spec.ts.

Commencer Voir sur GitHub Voir sur npm

Installation

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

Dernière release v0.13.0Licence MIT

Fichier compagnon par convention

users.controller.ts → users.controller.docs.ts. Le même schéma que Nest utilise déjà pour *.controller.spec.ts.

CLI avec garde-fous CI

check, coverage --min, lint et patch-spec. Fait échouer le build quand la documentation manque.

Inférence de type automatique

Interfaces, class-validator, et @HttpCode() deviennent un schéma OpenAPI sans décorateur supplémentaire.

Docfy UI pensé pour l'IA

Une interface de référence avec un bouton Copy for AI sur chaque endpoint, idéale à coller dans un LLM.

docfy-ui : une visionneuse de référence pensée pour l'IA

La spec OpenAPI que nestjs-docfy assemble est aussi ce que docfy-ui affiche, sans configuration séparée et avec la même source de vérité.

Copy for AI : un résumé déterministe et prêt pour un LLM de l'endpoint, pas un dump JSON brut avec des $ref
Recherche ⌘K sur tous les endpoints, instantanément
Détail complet de requête/réponse par endpoint, généré directement depuis la spec

docfy-ui detalhe de endpoint com Copy for AI

À quoi ça ressemble en pratique

Avant : un contrôleur noyé sous les décorateurs. Après : juste des routes, avec la documentation qui vit à côté, dans un fichier compagnon.

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

Uniquement au démarrage, aucun surcoût par requêteMême sortie OpenAPI que des décorateurs en ligneConvention de fichier compagnon, comme *.spec.ts

Aucun monkey-patching, aucun proxy runtime

Juste le bon timing et les métadonnées Reflect.

Écris le fichier compagnon

users.controller.docs.ts appelle docs(UsersController, { ... }), de simples décorateurs Swagger, juste dans un autre fichier.

Découvert au démarrage

DocfyModule.forRoot() le trouve grâce à la convention de nommage et écrit les métadonnées Reflect sur les méthodes du contrôleur, avant que SwaggerModule.createDocument() s'exécute.

Sortie OpenAPI identique

SwaggerModule voit exactement les mêmes métadonnées que si les décorateurs avaient été écrits en ligne sur le contrôleur.

Bien plus qu'unedoc Swagger.