API de Municípios Brasileiros

API RESTful para consulta de municípios brasileiros por estado (UF) com suporte a Docker

🌐 Frontend Vue.js

O projeto inclui um frontend Vue.js moderno para visualização dos municípios brasileiros. O frontend é servido na porta 3000 e se comunica com a API na porta 8000.

Acessando o Frontend

Com o Docker em execução, acesse:

• Frontend: http://localhost:3000
• API: http://localhost:8000

Documentação do Frontend

Para mais detalhes sobre a estrutura e como desenvolver o frontend, consulte o README do Frontend.

🚀 Começando

Pré-requisitos

• Docker e Docker Compose instalados
• Node.js 16+ (apenas para desenvolvimento do frontend)
• Git (opcional, apenas para clonar o repositório)

Instalação com Docker

1. Clone o repositório:

   git clone https://github.com/EricksonFerreira/idez_municipio.git
   cd idez_municipio

2. Crie o arquivo .env baseado no .env.example:

   cp .env.example .env

3. Inicie os contêineres:

   docker-compose up -d

4. Instale as dependências do Composer:

   docker-compose exec app composer install

5. Gere a chave da aplicação:

   docker-compose exec app php artisan key:generate

6. Instale as dependências do frontend e inicie o servidor de desenvolvimento:

   cd frontend
   npm install
   npm run dev

7. Acesse as aplicações em:

   • Frontend: http://localhost:3000
   • API: http://localhost:8000

Comandos úteis

• Parar os contêineres:

  docker-compose down

• Ver logs da aplicação:

  docker-compose logs -f app

• Acessar o terminal do container da aplicação:

  docker-compose exec app bash

🖥️ Frontend Vue.js

O frontend é uma aplicação Vue.js 3 com as seguintes características:

📦 Principais Dependências

• Vue 3 com Composition API
• Axios para requisições HTTP
• Tailwind CSS para estilização
• Vue Router para navegação
• Lodash para utilitários

🎨 Recursos

• Interface responsiva e moderna
• Lista de municípios em grid com 4 colunas
• Scroll infinito com carregamento automático
• Filtro por estado (UF)
• Exibição de código IBGE e informações detalhadas
• Animações e transições suaves

🛠️ Comandos Úteis

# Instalar dependências
npm install

# Iniciar servidor de desenvolvimento
npm run dev

# Compilar para produção
npm run build

# Executar testes
npm run test

📋 Sobre o Projeto

Esta é uma API RESTful desenvolvida em Laravel 12 que fornece informações sobre municípios brasileiros por estado (UF). A API consome dados de fontes externas (IBGE e BrasilAPI) e os disponibiliza em um formato padronizado, com suporte a paginação e cache para melhor desempenho.

🚀 Funcionalidades

• Consulta de municípios por UF
• Paginação de resultados
• Cache de respostas para melhor desempenho
• Suporte a múltiplos provedores de dados (IBGE, BrasilAPI)
• Documentação OpenAPI (Swagger) completa
• Testes automatizados

🔧 Provedores Suportados

• IBGE - Dados oficiais do Instituto Brasileiro de Geografia e Estatística
• BrasilAPI - Dados fornecidos pela BrasilAPI

Por padrão, o sistema utiliza o provedor configurado na variável de ambiente MUNICIPIOS_PROVIDER

🚀 Começando

📋 Pré-requisitos

• PHP 8.1 ou superior
• Composer
• Extensões PHP necessárias: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PCRE, PDO, Tokenizer, XML

🔧 Instalação

1. Clone o repositório:

   git clone https://github.com/EricksonFerreira/idez_municipio.git
   cd idez_municipio

2. Instale as dependências:

   composer install

3. Configure o ambiente:

   cp .env.example .env
   php artisan key:generate

4. Configure o provedor de municípios no arquivo .env:

   MUNICIPIOS_PROVIDER=IBGE  # ou BRASILAPI

5. (Opcional) Para desenvolvimento, você pode desativar a verificação SSL:

   MUNICIPIOS_VERIFY_SSL=false

🚀 Executando a aplicação

# Inicie o servidor de desenvolvimento
php artisan serve

# Execute os testes
php artisan test

📚 Documentação da API

A documentação interativa da API está disponível em /docs após a instalação. A documentação é gerada automaticamente a partir das anotações do código-fonte. OpenAPI (Swagger). Você pode visualizá-la de duas formas:

Visualizar online: Importe o arquivo docs/openapi.yaml em ferramentas como:

• Swagger Editor
• Stoplight Studio
• Redocly

📝 Endpoints

Listar Municípios por UF

GET /api/municipios/{uf}

Parâmetros de URL:

• uf (obrigatório): Sigla da Unidade Federativa (2 caracteres)

Parâmetros de consulta:

• page (opcional, padrão: 1): Número da página
• per_page (opcional, padrão: 10, máximo: 100): Itens por página

Exemplo de requisição:

curl -X GET "http://localhost:8000/api/municipios/PE?page=1&per_page=5" \
     -H "Accept: application/json"

Exemplo de resposta (200 OK):

{
  "current_page": 1,
  "data": [
    {
      "name": "Recife",
      "ibge_code": "2611606"
    },
    {
      "name": "Olinda",
      "ibge_code": "2609600"
    }
  ],
  "first_page_url": "http://localhost:8000/api/municipios/PE?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "http://localhost:8000/api/municipios/PE?page=1",
  "links": [
    {
      "url": null,
      "label": "« Anterior",
      "active": false
    },
    {
      "url": "http://localhost:8000/api/municipios/PE?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Próximo »",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "http://localhost:8000/api/municipios/PE",
  "per_page": 10,
  "prev_page_url": null,
  "to": 2,
  "total": 2
}

Códigos de status HTTP:

• 200: Sucesso
• 400: Formato de UF inválido
• 404: Nenhum município encontrado para a UF especificada
• 500: Erro interno do servidor

🧪 Testes

O projeto utiliza o framework de testes Pest PHP para testes unitários e de integração.

# Executar todos os testes
php artisan test

# Executar apenas testes unitários
php artisan test --testsuite=Unit

# Executar apenas testes de integração
php artisan test --testsuite=Feature

# Gerar relatório de cobertura de código (requer Xdebug)
XDEBUG_MODE=coverage php artisan test --coverage-html=coverage

🤝 Contribuindo

Contribuições são bem-vindas! Siga estes passos para contribuir:

1. Faça um Fork do projeto
2. Crie uma Branch para sua Feature (git checkout -b feature/AmazingFeature)
3. Adicione suas alterações (git add .)
4. Faça o Commit das suas alterações (git commit -m 'Add some AmazingFeature')
5. Faça o Push para a Branch (git push origin feature/AmazingFeature)
6. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.

📚 Aprendendo Laravel

O Laravel possui uma documentação extensiva e completa, além de uma biblioteca de tutoriais em vídeo, cobrindo todos os aspectos do framework.

Se você prefere aprender assistindo, o Laracasts oferece milhares de tutoriais em vídeo sobre Laravel, PHP moderno, testes e muito mais.

🛡️ Segurança

Se você descobrir uma vulnerabilidade de segurança, por favor envie um e-mail para o mantenedor do projeto. Todas as vulnerabilidades de segurança serão prontamente tratadas.

📄 Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.