Skip to content

API-DOCS.md

Latest commit

 

History

History
132 lines (99 loc) · 3.87 KB

API-DOCS.md

File metadata and controls

132 lines (99 loc) · 3.87 KB

Documentação da API Varion

📋 Visão Geral

A API Varion é um sistema RESTful para gerenciamento de projetos e tarefas, construído com Node.js, Express, TypeScript e TypeORM. A API fornece endpoints completos para gerenciar projetos, tarefas, comentários, itens de to-do e estados customizáveis.

🚀 Acesso à Documentação

Swagger UI (Recomendado)

A documentação interativa da API está disponível através do Swagger UI:

JSON Schema

O esquema OpenAPI 3.0 completo está disponível em:

📚 Recursos da Documentação

A documentação Swagger inclui:

  • ✅ Especificação completa de todos os endpoints
  • ✅ Esquemas de dados com validações Zod
  • ✅ Exemplos de requisições e respostas
  • ✅ Interface interativa para testar endpoints
  • ✅ Códigos de status e tratamento de erros
  • ✅ Agrupamento por funcionalidade (Projects, States, etc.)

🔗 Endpoints Principais

📁 Projetos (/projects)

  • POST / - Criar projeto
  • GET / - Listar projetos
  • GET /{code} - Detalhes do projeto
  • PUT /{code} - Atualizar projeto
  • POST /{code}/comments - Adicionar comentário

🏷️ Estados (/states)

  • POST / - Criar estado customizado
  • GET / - Listar estados
  • PUT /{id} - Atualizar estado
  • DELETE /{id} - Remover estado

📝 To-Do Items

  • POST /projects/todo/{code} - Adicionar item ao projeto
  • PUT /projects/todo/{id} - Atualizar item
  • DELETE /projects/todo/{id} - Remover item

🔧 Estrutura de Resposta

Todas as respostas da API seguem um padrão consistente:

✅ Sucesso

{
  "success": true,
  "data": { ... },
  "message": "Operação realizada com sucesso"
}

❌ Erro

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Dados inválidos fornecidos",
  "details": "O campo 'title' é obrigatório"
}

🎯 Códigos de Status HTTP

Código Significado Uso
200 OK Operação realizada com sucesso
201 Created Recurso criado com sucesso
400 Bad Request Dados inválidos ou mal formatados
404 Not Found Recurso não encontrado
409 Conflict Conflito (ex: nome já existe)
500 Internal Error Erro interno do servidor

🛡️ Validação de Dados

A API utiliza Zod para validação rigorosa de dados:

  • ✅ Validação de tipos e formatos
  • ✅ Mensagens de erro descritivas
  • ✅ Validação de parâmetros de rota
  • ✅ Validação de corpo da requisição
  • ✅ Transformação automática de dados

🔍 Exemplos de Uso

Criar um Projeto

curl -X POST http://localhost:3001/projects \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sistema de Vendas",
    "description": "Plataforma e-commerce completa",
    "deadline": "2024-12-31T23:59:59.000Z"
  }'

🚀 Como Testar

  1. Acesse a documentação: http://localhost:3001/api-docs
  2. Explore os endpoints organizados por tags
  3. Clique em "Try it out" em qualquer endpoint
  4. Preencha os parâmetros necessários
  5. Execute e veja a resposta em tempo real

🔗 Recursos Relacionados

🛠️ Tecnologias da Documentação

  • OpenAPI 3.0 - Especificação da API
  • Swagger UI - Interface interativa
  • swagger-jsdoc - Geração da documentação
  • swagger-ui-express - Servidor da documentação

Esta documentação é gerada automaticamente a partir dos comentários JSDoc no código e esquemas Zod de validação.