Mais do que apenas
Documentação Swagger.
nestjs-docfy separa a documentação Swagger/OpenAPI da lógica dos controllers usando um arquivo companheiro por convenção de nome, do mesmo jeito que o Nest já faz com *.controller.spec.ts.
npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadatadocfy-ui: um viewer de referência AI-first
A spec OpenAPI que o nestjs-docfy monta é a mesma que o docfy-ui renderiza, sem config separada e com a mesma fonte de verdade.
- Copy for AI: um resumo determinístico do endpoint pronto para LLM, não um dump de JSON com $ref
- Busca com ⌘K entre todos os endpoints, instantânea
- Detalhe completo de request/response por endpoint, gerado direto da spec
Feito para agentes de IA, não só para humanos
O docfy-mcp expõe seu OpenAPI spec como tools MCP, então Claude, Cursor ou qualquer agente compatível com MCP consulta sua API diretamente — sem colar JSON num prompt.
- list_endpoints / get_endpoint: navega e inspeciona qualquer operação, na mesma forma normalizada que o docfy-ui renderiza
- lint_spec: sinaliza summaries, descriptions, tags e respostas de erro faltando antes de irem pra produção
- diff_specs: compara dois documentos OpenAPI e sinaliza mudanças breaking vs. informativas
- contract_test: valida uma resposta real contra o schema declarado, direto das tool calls do próprio agente
- Zero-config contra um servidor NestJS rodando, ou aponte pra um arquivo de spec estático
{
"mcpServers": {
"docfy": {
"command": "npx",
"args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
}
}
}Como fica na prática
Antes: um controller enterrado em decorators. Depois: apenas rotas, com a documentação vivendo ao lado, em um arquivo companheiro.
@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' }),
],
},
});Sem monkey-patching, sem proxies em runtime
Só o timing certo e Reflect metadata.
Escreva o companion file
users.controller.docs.ts chama docs(UsersController, { ... }), decorators Swagger normais, só que em outro arquivo.
Descoberto no boot
DocfyModule.forRoot() encontra por convenção de nome e escreve Reflect metadata nos métodos do controller, antes do SwaggerModule.createDocument() rodar.
Output OpenAPI idêntico
O SwaggerModule vê exatamente a mesma metadata que veria se os decorators estivessem inline no controller.
Não é um plugin de Swagger. É o toolchain inteiro.
A maioria das ferramentas para nos decorators. O nestjs-docfy entrega a CLI, o viewer e a integração com IA que seu time realmente precisa pra manter a documentação honesta.
Uma CLI que trava seu CI
generate, check, coverage --min, lint e patch-spec falham o build no exato momento em que a documentação diverge do código — não meses depois.
Custo zero em runtime, se você quiser
O plugin webpack da CLI calcula tudo em build time; nada roda por requisição em produção.
docfy-ui incluído, não vendido separado
Um viewer de referência AI-first completo já vem com a lib — sem conta extra, sem plano à parte.
Agentes como cidadãos de primeira classe
O docfy-mcp expõe a mesma spec pro Claude, Cursor e qualquer client MCP — sua API vira consultável, não só legível.
Funciona com o layout de NestJS que você já tem
Projetos simples, workspaces Nx e monorepos Nest CLI são todos auto-detectados — nenhum arquivo de config pra escrever à mão.
Um comando do zero ao setup completo
O nestjs-docfy init conecta o módulo, decora todo controller e gera os docs — numa tacada só.