Device Ping API

Jednoduché REST API pre správu zariadení a ich pingov postavené na Laravel 13.

Požiadavky

• PHP 8.3+
• Composer
• MySQL alebo PostgreSQL (lokálne)
• Docker a Docker Compose (voliteľné)

API endpointy

Metóda	Endpoint	Popis
POST	/api/devices	Vytvorenie zariadenia
GET	/api/devices	Zoznam zariadení
GET	/api/devices/{uuid}	Detail zariadenia
POST	/api/devices/{uuid}/ping	Uloženie pingu

Swagger dokumentácia

Interaktívna OpenAPI dokumentácia so Swagger UI rozhraním je dostupná na:

http://localhost:8000/api/documentation

Poznámka: Otvorte /api/documentation, nie /docs ani /docs?api-docs.json — tie vracajú surový JSON bez vizuálneho rozhrania.

Čo uvidíte

Swagger UI zobrazí prehľadnú webovú dokumentáciu:

• nadpis Device Ping API a popis
• sekcia Devices so zoznamom endpointov
• farebné HTTP metódy (GET modrá, POST zelená)
• po rozkliknutí endpointu: parametre, request body, odpovede
• tlačidlo Try it out na priame volanie API z prehliadača

Nastavenie vzhľadu

V .env môžete upraviť:

L5_SWAGGER_UI_DOC_EXPANSION=list   # list | full | none
L5_SWAGGER_UI_DARK_MODE=false       # true = tmavý režim

Vygenerovanie dokumentácie:

php artisan l5-swagger:generate

V lokálnom prostredí sa dokumentácia regeneruje automaticky (L5_SWAGGER_GENERATE_ALWAYS=true v .env).

Lokálne spustenie

1. Inštalácia závislostí

composer install

2. Nastavenie .env

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

Upravte databázové nastavenia v .env:

MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=be
DB_USERNAME=root
DB_PASSWORD=

PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=be
DB_USERNAME=postgres
DB_PASSWORD=

3. Migrácie

php artisan migrate

4. Demo dáta (voliteľné)

Pre rýchle manuálne testovanie API alebo Swagger UI:

php artisan db:seed

Vytvorí zariadenie Sensor 01 s ukážkovým pingom (battery_percent: 85).

5. Spustenie testov

php artisan test --compact

Testy používajú SQLite in-memory databázu (nastavenú v phpunit.xml), takže nie je potrebná samostatná testovacia databáza.

6. Spustenie aplikácie

php artisan serve

API bude dostupné na adrese http://localhost:8000/api.

Spustenie cez Docker

1. Inštalácia a konfigurácia

cp .env.example .env

Pre Docker nastavte v .env:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=be
DB_USERNAME=be
DB_PASSWORD=secret

2. Spustenie kontajnerov

docker compose up -d --build

3. Migrácie a demo dáta

docker compose exec app php artisan migrate
docker compose exec app php artisan db:seed

4. Spustenie testov

docker compose exec app php artisan test --compact

Aplikácia beží na http://localhost:8000.

Príklady volaní API

Vytvorenie zariadenia

curl -X POST http://localhost:8000/api/devices \
  -H "Content-Type: application/json" \
  -d '{"uuid":"550e8400-e29b-41d4-a716-446655440000","name":"Sensor 01"}'

Uloženie pingu

curl -X POST http://localhost:8000/api/devices/550e8400-e29b-41d4-a716-446655440000/ping \
  -H "Content-Type: application/json" \
  -d '{"battery_percent":85}'

Detail zariadenia

curl http://localhost:8000/api/devices/550e8400-e29b-41d4-a716-446655440000

Zoznam zariadení

curl http://localhost:8000/api/devices

Štruktúra projektu

• app/Models/ – Eloquent modely Device a Ping
• app/Http/Controllers/Api/ – API controller
• app/Http/Requests/ – FormRequest validácie
• app/Http/Resources/ – API Resource triedy
• database/migrations/ – databázové migrácie
• database/seeders/ – demo dáta pre lokálny vývoj
• tests/Feature/DeviceApiTest.php – feature testy API
• tests/Feature/DeviceSeederTest.php – testy seedera