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.13.0Licenza 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

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.

Più di una semplicedocumentazione Swagger.