Più di una semplice
documentazione Swagger.

nestjs-docfy separa la documentazione Swagger/OpenAPI dalla logica dei controller usando una convenzione di file companion, esattamente come Nest fa già con *.controller.spec.ts.

Inizia subito Vedi su GitHub Vedi su npm

Installation

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

Ultima release v0.18.1Licenza MIT

File companion per convenzione

users.controller.ts → users.controller.docs.ts. Lo stesso pattern che Nest usa già per *.controller.spec.ts.

CLI con gate per la CI

check, coverage --min, lint e patch-spec. Fa fallire la build quando manca la documentazione.

Inferenza automatica dei tipi

Interface, class-validator e @HttpCode() diventano uno schema OpenAPI senza decorator aggiuntivi.

Docfy UI AI-first

Una UI di riferimento con un pulsante Copy for AI su ogni endpoint, ideale da incollare negli LLM.

docfy-ui: un visualizzatore di riferimento AI-first

La spec OpenAPI che nestjs-docfy assembla è anche ciò che docfy-ui renderizza, senza configurazione separata e con la stessa fonte di verità.

Copy for AI: un riepilogo deterministico e pronto per LLM dell'endpoint, non un dump JSON grezzo con $ref
Ricerca ⌘K su ogni endpoint, all'istante
Dettaglio completo di richiesta/risposta per ogni endpoint, generato direttamente dalla spec

docfy-ui detalhe de endpoint com Copy for AI

Costruito per agenti IA, non solo per umani

docfy-mcp espone la tua spec OpenAPI come tool MCP, così Claude, Cursor o qualsiasi agente compatibile con MCP interroga la tua API direttamente, senza incollare JSON in un prompt.

list_endpoints / get_endpoint: sfoglia e ispeziona qualsiasi operazione, nella stessa forma normalizzata che docfy-ui renderizza
lint_spec: segnala summary, descrizioni, tag e risposte di errore mancanti prima che vadano in produzione
diff_specs: confronta due documenti OpenAPI e segnala cambiamenti breaking vs. informativi
contract_test: valida una risposta reale rispetto al suo schema dichiarato, direttamente dalle tool call dell'agente
Zero configurazione contro un server NestJS in esecuzione, oppure punta a un file di spec statico

claude_desktop_config.json

{
  "mcpServers": {
    "docfy": {
      "command": "npx",
      "args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
    }
  }
}

Esplora docfy-mcp

Come si presenta nella pratica

Prima: un controller sommerso di decorator. Dopo: solo rotte, con la documentazione che vive accanto, in un file companion.

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

Solo all'avvio, zero overhead per richiestaStesso output OpenAPI dei decorator inlineConvenzione a file companion, come *.spec.ts

Nessun monkey-patching, nessun proxy a runtime

Solo il timing giusto e i metadati Reflect.

Scrivi il file companion

users.controller.docs.ts chiama docs(UsersController, { ... }), normali decorator Swagger, solo in un altro file.

Scoperto all'avvio

DocfyModule.forRoot() lo trova tramite la convenzione di denominazione e scrive i metadati Reflect sui metodi del controller, prima che venga eseguito SwaggerModule.createDocument().

Output OpenAPI identico

SwaggerModule vede esattamente gli stessi metadati che vedrebbe se i decorator fossero scritti inline sul controller.

Non è un plugin Swagger. È l'intera toolchain.

La maggior parte degli strumenti si ferma ai decoratori. nestjs-docfy offre la CLI, il viewer e l'integrazione IA di cui il tuo team ha davvero bisogno per mantenere onesta la documentazione.

Una CLI che blocca la tua CI

generate, check, coverage --min, lint e patch-spec fanno fallire la build nel momento in cui la documentazione si discosta dal codice, non mesi dopo.

Costo runtime zero, se lo vuoi

Il plugin webpack della CLI calcola tutto in fase di build; niente gira per richiesta in produzione.

docfy-ui incluso, non venduto a parte

Un viewer di riferimento AI-first completo è incluso nella libreria: nessun account extra, nessun piano separato.

Agenti come cittadini di prima classe

docfy-mcp espone la stessa spec a Claude, Cursor e qualsiasi client MCP, la tua API diventa interrogabile, non solo leggibile.

Funziona con il layout NestJS che hai già

Progetti semplici, workspace Nx e monorepo Nest CLI vengono tutti rilevati automaticamente, nessun file di config da scrivere a mano.

Un comando da zero a tutto collegato

nestjs-docfy init collega il modulo, decora ogni controller e genera i docs, tutto in un colpo solo.

Vedi tutta la documentazione

Più di una semplicedocumentazione Swagger.