Kataem API

Laravel 12 API backend with Sanctum auth, OpenAPI 3.0 (Swagger), UUIDv7 primary keys.

Stack

• PHP 8.2, Laravel 12
• Auth: Laravel Sanctum (token)
• API: JSON only, versioned /api/v1
• Docs: l5-swagger (auto from annotations) + docs/openapi.yaml
• IDs: UUID v7 (App\Models\Concerns\HasUuidV7 + UuidV7Service)

Standards

• PSR-12: форматирование (при наличии: ./vendor/bin/pint --test).
• Типизация: declare(strict_types=1); в Support, Middleware, Policies, части Controllers.
• Ответы API: единый формат через App\Support\ApiResponse (success: data/meta, error: message/errors). Исключения для api/* обрабатываются в bootstrap/app.php (JSON с тем же форматом).
• Права: Gate admin, ResortPolicy; create/update/delete для Resorts и вложенных ресурсов — только для admin (middleware auth:sanctum + admin).
• Swagger: пути в аннотациях соответствуют роутам /api/v1/....

Подробно: docs/project-structure-and-run.md.

Structure

app/
├── Contracts/          # Interfaces (Repositories, Services)
├── DTO/                # Data transfer objects
├── Features/           # Use cases (Auth, User, Resort, Hotel, …)
├── Http/
│   ├── Controllers/Api/V1/
│   ├── Middleware/     # EnsureJsonRequest, EnsureUserIsAdmin
│   ├── Requests/Api/V1/
│   └── Resources/Api/V1/
├── Models/             # Eloquent (BaseModel + UUIDv7)
├── Policies/           # ResortPolicy (admin for create/update/delete)
├── Repositories/       # Implementations of Contracts
├── Services/           # AuthService, UuidV7Service
└── Support/            # ApiResponse (success/error)

Local (Docker)

cp .env.example .env
docker compose up --build

• API: http://localhost:8000
• Swagger UI: http://localhost:8000/api/documentation
• Health: http://localhost:8000/up

Production build

docker build --build-arg INSTALL_DEV=0 -t kataem-api .

API examples

Register

curl -s -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","email":"test@example.com","password":"password","password_confirmation":"password"}'

Login

curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password"}'

Me (with token)

curl -s http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Swagger

• Auto: run php artisan l5-swagger:generate (or set L5_SWAGGER_GENERATE_ALWAYS=true).
• Static: docs/openapi.yaml in repo.

Without Docker

composer install
cp .env.example .env && php artisan key:generate
# set DB_* in .env
php artisan migrate
php artisan l5-swagger:generate
php artisan serve