Más que solo
documentación Swagger.
nestjs-docfy separa la documentación Swagger/OpenAPI de la lógica del controller usando una convención de nombres de archivo companion, de la misma forma en que Nest ya lo hace con *.controller.spec.ts.
npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadatadocfy-ui: un visor de referencia AI-first
La spec OpenAPI que ensambla nestjs-docfy es también lo que renderiza docfy-ui, sin configuración aparte y con la misma fuente de verdad.
- Copy for AI: un resumen determinista del endpoint, listo para LLM, no un volcado de JSON crudo con $ref
- Búsqueda con ⌘K en todos los endpoints, al instante
- Detalle completo de request/response por endpoint, generado directamente desde la spec
Hecho para agentes de IA, no solo para humanos
docfy-mcp expone tu spec de OpenAPI como tools MCP, así que Claude, Cursor o cualquier agente compatible con MCP consulta tu API directamente — sin pegar JSON en un prompt.
- list_endpoints / get_endpoint: explora e inspecciona cualquier operación, con la misma forma normalizada que renderiza docfy-ui
- lint_spec: señala summaries, descriptions, tags y respuestas de error faltantes antes de publicarse
- diff_specs: compara dos documentos OpenAPI y señala cambios breaking vs. informativos
- contract_test: valida una respuesta real contra su schema declarado, desde las tool calls del propio agente
- Zero-config contra un servidor NestJS en ejecución, o apunta a un archivo de spec estático
{
"mcpServers": {
"docfy": {
"command": "npx",
"args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
}
}
}Cómo se ve en la práctica
Antes: un controller enterrado en decorators. Después: solo rutas, con la documentación viviendo al lado, en un archivo companion.
@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' }),
],
},
});Sin monkey-patching, sin proxies en runtime
Solo el timing correcto y metadata de Reflect.
Escribe el archivo companion
users.controller.docs.ts llama a docs(UsersController, { ... }), decorators de Swagger normales, solo que en otro archivo.
Descubierto al arrancar
DocfyModule.forRoot() lo encuentra vía la convención de nombres y escribe metadata de Reflect en los métodos del controller, antes de que se ejecute SwaggerModule.createDocument().
Salida OpenAPI idéntica
SwaggerModule ve exactamente la misma metadata que vería si los decorators estuvieran escritos inline en el controller.
No es un plugin de Swagger. Es todo el toolchain.
La mayoría de las herramientas se quedan en los decoradores. nestjs-docfy trae la CLI, el visor y la integración con IA que tu equipo realmente necesita para mantener la documentación honesta.
Una CLI que bloquea tu CI
generate, check, coverage --min, lint y patch-spec fallan el build en el momento en que la documentación se desalinea del código — no meses después.
Costo cero en runtime, si quieres
El plugin de webpack de la CLI calcula todo en build time; nada corre por request en producción.
docfy-ui incluido, no vendido aparte
Un visor de referencia AI-first completo viene con la librería — sin cuenta extra, sin plan aparte.
Agentes como ciudadanos de primera clase
docfy-mcp expone la misma spec a Claude, Cursor y cualquier cliente MCP — tu API se vuelve consultable, no solo legible.
Funciona con el layout de NestJS que ya tienes
Proyectos simples, workspaces de Nx y monorepos de Nest CLI se detectan automáticamente — sin archivo de config que escribir a mano.
Un comando de cero a todo conectado
nestjs-docfy init conecta el módulo, decora cada controller y genera los docs — de una sola vez.