README
¶
StayKey API
StayKey API é um backend moderno para gerenciamento de reservas de hospedagens, inspirado em soluções como Airbnb.
A API fornece recursos para cadastro de usuários, propriedades, reservas e check-in via QR Code, com foco em simplicidade, escalabilidade e segurança.
🚀 Tecnologias
- Go — linguagem principal
- PostgreSQL — banco de dados
- Tern — ferramenta de migração de banco
- Air — hot reload para desenvolvimento
- Swagger 2.0 — documentação da API
- Docker (opcional) — ambiente isolado de desenvolvimento
⚙️ Variáveis de Ambiente
Crie um arquivo .env na raiz do projeto com o seguinte conteúdo:
PORT=8080
ENV="dev"
STAYKEY_DATABASE_PORT=5432
STAYKEY_DATABASE_USER="postgres"
STAYKEY_DATABASE_PASSWORD="postgres"
STAYKEY_DATABASE_NAME="staykey"
STAYKEY_DATABASE_HOST="localhost"
ACCESS_TOKEN_SECRET="secret"
REFRESH_TOKEN_SECRET="secret"
▶️ Execução da Aplicação
Rodar com Air (modo desenvolvimento)
make run
Rodar sem Air
make start
Compilar o binário
make build
A API iniciará em:
👉 http://localhost:8080/api
🗄️ Migrações de Banco de Dados
Executar migrações usando cmd/terndotenv/main.go:
Rodar todas as migrações
make migrate-up
Rodar até uma versão específica
make migrate-up-to 3
Reverter uma migração
make migrate-down
Reverter até uma versão específica
make migrate-down-to 1
🧪 Testes
Executar testes unitários
make test
Executar testes de integração
make test-integration
Executar testes end-to-end
make test-e2e
Rodar todos os testes
make test-all
📚 Documentação Swagger
Gerar e limpar documentação da API:
Gerar documentação
make swagger-v1
Limpar documentação gerada
make swagger-clean
A documentação será gerada em:
📂 docs/v1
Acessar via navegador
🌐 Swagger UI: http://localhost:8080/api/v1/docs/index.html#/
🧰 Comandos do Makefile
Principais comandos para desenvolvimento:
make run # Executa a API com Air (hot reload)
make start # Executa a API sem Air
make build # Compila o binário
make test # Executa os testes unitários
make test-all # Executa todos os testes (unit, integration e e2e)
make migrate-up # Executa todas as migrações
make migrate-down # Reverte a última migração
make swagger-v1 # Gera documentação Swagger
📚 Endpoints Principais
A documentação completa está disponível no Swagger UI:
👉 http://localhost:8080/api/v1/docs/index.html#/
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /api/v1/users |
Cria um novo usuário |
| GET | /api/v1/users/me |
Retorna o usuário autenticado |
| POST | /api/v1/properties |
Cria uma nova propriedade (host) |
| GET | /api/v1/properties |
Lista propriedades com filtros |
| POST | /api/v1/reservations |
Cria uma nova reserva |
| PATCH | /api/v1/reservations/{id}/cancel |
Cancela uma reserva |
| POST | /api/v1/access/{reservation_id}/qrcode |
Gera QR Code de acesso |
| POST | /api/v1/access/validate/qrcode |
Valida um QR Code de reserva |
🔐 Autenticação
A API utiliza Bearer Token JWT.
Após autenticar, inclua o cabeçalho em suas requisições:
Authorization: Bearer <token>
🧱 Estrutura dos Principais Domínios
- Usuários (
users) — cadastro, autenticação, exclusão e detalhes - Propriedades (
properties) — CRUD para hosts - Reservas (
reservations) — criação, listagem, confirmação e cancelamento - Acesso (
access) — geração e validação de QR Codes
🧾 Licença
Distribuído sob a licença MIT.
Sinta-se livre para usar, modificar e contribuir!
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
api
command
|
|
|
terndotenv
command
|
|
|
docs
|
|
|
v1
Package v1 Code generated by swaggo/swag.
|
Package v1 Code generated by swaggo/swag. |
|
internal
|
|
|
pkg
|
|