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.
npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadatadocfy-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
Conçu pour les agents IA, pas seulement pour les humains
docfy-mcp expose ta spec OpenAPI sous forme d'outils MCP, pour que Claude, Cursor ou tout agent compatible MCP interroge ton API directement — sans copier-coller du JSON dans un prompt.
- list_endpoints / get_endpoint : parcourt et inspecte n'importe quelle opération, avec la même forme normalisée que docfy-ui affiche
- lint_spec : signale les summaries, descriptions, tags et réponses d'erreur manquants avant leur mise en production
- diff_specs : compare deux documents OpenAPI et signale les changements cassants vs. informatifs
- contract_test : valide une réponse réelle par rapport à son schéma déclaré, depuis les appels d'outils de l'agent lui-même
- Zéro configuration contre un serveur NestJS en cours d'exécution, ou pointe vers un fichier de spec statique
{
"mcpServers": {
"docfy": {
"command": "npx",
"args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
}
}
}À 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.
@WithDocs()
@Controller('users')
export class UsersController {
constructor(private readonly users: UsersService) {}
@Get(':id')
findOne(@Param('id') id: string) {
return this.users.findOne(id);
}
}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' }),
],
},
});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.
Pas un plugin Swagger. Toute la chaîne d'outils.
La plupart des outils s'arrêtent aux décorateurs. nestjs-docfy fournit la CLI, le viewer et l'intégration IA dont ton équipe a vraiment besoin pour garder une documentation fiable.
Une CLI qui verrouille ta CI
generate, check, coverage --min, lint et patch-spec font échouer le build dès que la documentation s'écarte du code — pas des mois plus tard.
Coût runtime nul, si tu le souhaites
Le plugin webpack de la CLI calcule tout au moment du build ; rien ne s'exécute par requête en production.
docfy-ui inclus, pas vendu séparément
Un viewer de référence AI-first complet est fourni avec la librairie — pas de compte supplémentaire, pas de palier tarifaire séparé.
Les agents comme citoyens de première classe
docfy-mcp expose la même spec à Claude, Cursor et tout client MCP — ton API devient interrogeable, pas seulement lisible.
Fonctionne avec la structure NestJS que tu as déjà
Projets simples, workspaces Nx et monorepos Nest CLI sont tous détectés automatiquement — aucun fichier de config à écrire à la main.
Une commande, de zéro à tout connecté
nestjs-docfy init connecte le module, décore chaque contrôleur et génère les docs — en une seule fois.