# ControlOne API — Portale documentazione

Portale statico di documentazione REST API per **ControlOne**, pubblicabile su un sottodominio dedicato (es. `https://api.controllone.com`), in stile [Frotcom API Reference](https://v2api.frotcom.com/documentation/index.html).

## Contenuto

| File | Descrizione |
|------|-------------|
| `index.html` | Documentazione interattiva Swagger UI |
| `tutorial.html` | Guida rapida (autenticazione, esempi, deploy) |
| `openapi.yaml` | Specifica OpenAPI 3.0 con tutte le API ControlOne |
| `assets/` | CSS e favicon |

## API documentate (37 endpoint)

- **Account** — login, profilo, notifiche, password
- **Dashboard** — statistiche flotta
- **Vehicles** — anagrafica e eventi
- **Fleet** — posizione live, dettagli, cronologia GPS
- **Reports** — generazione ed export PDF/CSV
- **Geofences** — CRUD zone e assegnazione veicoli
- **RouteTracking** — aggiornamento percorsi (parser)
- **Device** — eventi Teltonika e comandi

## Anteprima locale

### Opzione A — Python (consigliata)

```bash
cd "API (Documentation Portal)"
python -m http.server 8080
```

Apri: http://localhost:8080

### Opzione B — Node.js

```bash
cd "API (Documentation Portal)"
npx --yes serve -l 8080
```

### Opzione C — Docker

```bash
cd "API (Documentation Portal)"
docker compose up -d
```

Apri: http://localhost:8080

## Pubblicazione su api.controllone.com

### 1. DNS

Crea un record **A** o **CNAME**:

```
api.controllone.com  →  IP del server web
```

### 2. Copia file sul server

```bash
# Esempio con rsync
rsync -avz --delete \
  "API (Documentation Portal)/" \
  user@server:/var/www/api.controllone.com/
```

Oppure via SFTP/FileZilla nella cartella `/var/www/api.controllone.com/`.

### 3. Nginx (esempio)

Vedi `nginx.conf.example`. Configurazione minima:

```nginx
server {
    listen 443 ssl http2;
    server_name api.controllone.com;

    root /var/www/api.controllone.com;
    index index.html;

    ssl_certificate     /etc/letsencrypt/live/api.controllone.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.controllone.com/privkey.pem;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(yaml|yml|json)$ {
        add_header Access-Control-Allow-Origin *;
        add_header Content-Type application/yaml;
    }
}
```

Certificato SSL con Certbot:

```bash
sudo certbot --nginx -d api.controllone.com
```

### 4. HTTPS redirect

```nginx
server {
    listen 80;
    server_name api.controllone.com;
    return 301 https://$host$request_uri;
}
```

### 5. Verifica

- https://api.controllone.com — Swagger UI
- https://api.controllone.com/tutorial.html — Tutorial
- https://api.controllone.com/openapi.yaml — Spec scaricabile

## Aggiornare la documentazione

1. Modifica `openapi.yaml` quando aggiungi endpoint in `Platform/routes/api.php`
2. Ricopia la cartella sul server
3. Non serve riavviare Laravel — è sito statico

## Integrazione con Laravel (opzionale)

Se preferisci servire la doc dalla stessa app Laravel:

```php
// routes/web.php
Route::redirect('/api-docs', 'https://api.controllone.com');
```

Oppure monta i file statici in `public/api-docs/`.

## Note sicurezza

- Il portale documenta anche endpoint **senza auth** (Device, RouteTracking)
- In produzione limita quegli endpoint per IP sul server Laravel
- Non inserire credenziali reali negli esempi Swagger

## Riferimenti

- [OpenAPI Specification](https://swagger.io/specification/)
- [Swagger UI](https://swagger.io/tools/swagger-ui/)
- Backend API: `Platform (Web APP, APIs, Python Parser)/routes/api.php`