Vesta

Biblioteca TypeScript para geração automática de documentação de API, usando decorators.

Características

• Decorators TypeScript - Documente suas rotas com decorators simples
• Scanner Automático - Escaneia automaticamente seus controllers
• Documentação Interativa - Gera uma interface web moderna e responsiva
• Tags e Filtros - Organize suas rotas por tags
• Suporte a Segurança - Documente esquemas de autenticação
• Type-Safe - Totalmente tipado com TypeScript

Instalação

npm install @lukau-garcia/vesta --save-dev

Uso Rápido

1. Instale a biblioteca

npm install @lukau-garcia/vesta --save-dev

2. Configure o TypeScript

Certifique-se de que seu tsconfig.json tem decorators habilitados:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

3. Use o decorator nos seus controllers

import { vesta } from "@lukau-garcia/vesta";

export class UserController {
  @vesta({
    method: "GET",
    path: "/api/users",
    summary: "Lista todos os utilizadores",
    description: "Retorna uma lista paginada de utilizadores",
    tags: ["Users"],
    parameters: [
      {
        name: "page",
        in: "query",
        description: "Número da página",
        required: false,
        type: "number"
      }
    ],
    responses: [
      {
        status: 200,
        description: "Lista de utilizadores retornada com sucesso"
      }
    ],
    security: [
      {
        type: "bearer",
        scheme: "JWT"
      }
    ]
  })
  listUsers() {
    // Sua implementação
  }
}

4. Importe os controllers

Crie um arquivo que importe todos os controllers (para que os decorators sejam executados):

// src/index.ts
import "./controllers/UserController";
import "./controllers/ProductController";

5. Gere a documentação

npx vesta generate --title "Minha API" --version "1.0.0"

6. Configure o middleware no seu servidor

import express from 'express';
import { vestaMiddleware } from '@lukau-garcia/vesta';

const app = express();

// Servir documentação em /docs
app.use('/docs', vestaMiddleware());

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Documentation: http://localhost:3000/docs');
});

7. Visualize a documentação

Acesse http://localhost:3000/docs no seu navegador.

Documentação Completa

Opções do Decorator

@vesta({
  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD",
  path?: string,                    // Path da rota (padrão: /nomeDoMetodo)
  summary?: string,                 // Resumo curto
  description?: string,             // Descrição detalhada
  tags?: string[],                  // Tags para organização
  parameters?: Parameter[],         // Parâmetros da rota
  responses?: Response[],           // Respostas possíveis
  security?: SecurityScheme[],      // Esquemas de segurança
  entity?: {                        // Entidade relacionada
    name: string,
    description?: string
  },
  deprecated?: boolean,             // Marca como deprecated
  operationId?: string              // ID único da operação
})

Exemplos de Parâmetros

parameters: [
  {
    name: "id",
    in: "path",              // "query" | "path" | "header" | "body"
    description: "ID do usuário",
    required: true,
    type: "string"
  },
  {
    name: "page",
    in: "query",
    description: "Número da página",
    required: false,
    type: "number"
  }
]

Exemplos de Respostas

responses: [
  {
    status: 200,
    description: "Sucesso",
    example: { users: [] }
  },
  {
    status: 404,
    description: "Não encontrado"
  }
]

Exemplos de Segurança

security: [
  {
    type: "bearer",
    scheme: "JWT"
  },
  {
    type: "apiKey",
    name: "X-API-Key",
    in: "header"
  }
]

Comandos CLI

# Gerar documentação
vesta generate

# Com opções customizadas
vesta generate --title "Minha API" --version "1.0.0" --description "Descrição da API"

# Especificar caminho do projeto
vesta generate --path ./meu-projeto

# Ajuda
vesta help

Estrutura de Arquivos Gerados

Após executar vesta generate, será criada a pasta docs/ com:

docs/
├── index.html    # Interface web da documentação
├── ui.js         # JavaScript da interface
└── vesta.json    # Dados estruturados da documentação

Interface

A interface gerada inclui:

• Filtro por tags
• Badges coloridos por método HTTP
• Detalhes completos de parâmetros e respostas
• Informações de segurança
• Design responsivo
• Botão de teste para cada rota (permite testar a API diretamente da documentação)

Servir Documentação no Servidor da Aplicação

O Vesta fornece um middleware Express para servir a documentação diretamente no seu servidor da aplicação. Isso permite que a documentação esteja disponível no arranque do servidor, sem necessidade de um servidor separado.

Uso com Express

import express from 'express';
import { vestaMiddleware } from '@lukau-garcia/vesta';

const app = express();

// Servir documentação em /docs
app.use('/docs', vestaMiddleware());

// Ou com caminho customizado
app.use('/api-docs', vestaMiddleware({
  docsPath: './custom-docs-path'
}));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Documentation available at http://localhost:3000/docs');
});

Opções do Middleware

vestaMiddleware({
  docsPath?: string  // Caminho para a pasta docs (padrão: process.cwd() + "/docs")
})

Características

• ✅ Serve automaticamente os arquivos estáticos (index.html, ui.js, vesta.json)
• ✅ Detecta automaticamente a pasta docs/ no projeto
• ✅ Valida se a documentação existe antes de iniciar
• ✅ Suporta diferentes tipos de arquivo (HTML, JS, JSON, imagens, etc.)
• ✅ Proteção contra directory traversal
• ✅ Content-Type correto para cada tipo de arquivo

Nota: Execute vesta generate antes de usar o middleware para gerar a documentação.

🔧 Configuração Avançada

Múltiplos Controllers

// src/controllers/UserController.ts
export class UserController {
  @vesta({ method: "GET", path: "/users", tags: ["Users"] })
  list() { }
}

// src/controllers/ProductController.ts
export class ProductController {
  @vesta({ method: "GET", path: "/products", tags: ["Products"] })
  list() { }
}

// src/index.ts - Importe todos
import "./controllers/UserController";
import "./controllers/ProductController";

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

Licença

ISC

Agradecimentos

Inspirado no Swagger/OpenAPI, mas com uma abordagem mais simples e focada em TypeScript.