523 lines
15 KiB
YAML
523 lines
15 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Travel Router Control API
|
|
description: |
|
|
API for controlling a mini travel router with dual WiFi interfaces and Ethernet connectivity.
|
|
The router can operate as a WiFi repeater, connecting to upstream networks while providing
|
|
a hotspot for client devices.
|
|
version: 1.0.0
|
|
contact:
|
|
name: API Support
|
|
license:
|
|
name: MIT
|
|
|
|
servers:
|
|
- url: http://localhost:8080
|
|
description: Local router API
|
|
|
|
tags:
|
|
- name: WiFi
|
|
description: WiFi client operations (upstream network connection)
|
|
- name: Hotspot
|
|
description: Access point operations (client-facing hotspot)
|
|
- name: Devices
|
|
description: Connected devices management
|
|
- name: System
|
|
description: System status and monitoring
|
|
- name: Logs
|
|
description: System logs and real-time monitoring
|
|
|
|
paths:
|
|
/api/wifi/scan:
|
|
get:
|
|
tags:
|
|
- WiFi
|
|
summary: Scan for available WiFi networks
|
|
description: |
|
|
Triggers a WiFi scan using wpa_supplicant via D-Bus and returns all discovered networks
|
|
sorted by signal strength. The scan takes approximately 2 seconds to complete.
|
|
operationId: scanWiFi
|
|
responses:
|
|
'200':
|
|
description: Successfully scanned networks
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/WiFiNetwork'
|
|
example:
|
|
- ssid: "Hotel-Guest"
|
|
signal: 5
|
|
security: "WPA2"
|
|
channel: 6
|
|
bssid: "aa:bb:cc:dd:ee:ff"
|
|
- ssid: "Public-WiFi"
|
|
signal: 3
|
|
security: "Open"
|
|
channel: 11
|
|
bssid: "11:22:33:44:55:66"
|
|
'500':
|
|
description: Scan error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/wifi/connect:
|
|
post:
|
|
tags:
|
|
- WiFi
|
|
summary: Connect to a WiFi network
|
|
description: |
|
|
Connects the router to an upstream WiFi network using wpa_supplicant.
|
|
Supports both open and password-protected networks (WPA/WPA2).
|
|
operationId: connectWiFi
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WiFiConnectRequest'
|
|
examples:
|
|
protected:
|
|
summary: WPA2 protected network
|
|
value:
|
|
ssid: "Hotel-Guest"
|
|
password: "guest1234"
|
|
open:
|
|
summary: Open network
|
|
value:
|
|
ssid: "Public-WiFi"
|
|
password: ""
|
|
responses:
|
|
'200':
|
|
description: Successfully connected
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
'400':
|
|
description: Invalid request data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
description: Connection failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/wifi/disconnect:
|
|
post:
|
|
tags:
|
|
- WiFi
|
|
summary: Disconnect from WiFi network
|
|
description: |
|
|
Disconnects from the currently connected upstream WiFi network
|
|
and removes all saved network configurations.
|
|
operationId: disconnectWiFi
|
|
responses:
|
|
'200':
|
|
description: Successfully disconnected
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
'500':
|
|
description: Disconnection failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/hotspot/config:
|
|
post:
|
|
tags:
|
|
- Hotspot
|
|
summary: Configure hotspot settings
|
|
description: |
|
|
Updates the hotspot (access point) configuration including SSID, password,
|
|
and WiFi channel. Changes are written to hostapd configuration file.
|
|
The hotspot needs to be restarted for changes to take effect.
|
|
operationId: configureHotspot
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HotspotConfig'
|
|
responses:
|
|
'200':
|
|
description: Configuration updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
'400':
|
|
description: Invalid configuration data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
description: Configuration update failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/hotspot/toggle:
|
|
post:
|
|
tags:
|
|
- Hotspot
|
|
summary: Toggle hotspot on/off
|
|
description: |
|
|
Enables or disables the hotspot (access point) by starting/stopping
|
|
the hostapd service. Returns the new enabled state.
|
|
operationId: toggleHotspot
|
|
responses:
|
|
'200':
|
|
description: Hotspot state changed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
description: Current hotspot state after toggle
|
|
required:
|
|
- enabled
|
|
example:
|
|
enabled: true
|
|
'500':
|
|
description: Failed to change hotspot state
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/devices:
|
|
get:
|
|
tags:
|
|
- Devices
|
|
summary: Get connected devices
|
|
description: |
|
|
Returns a list of all devices currently connected to the hotspot.
|
|
Device information is gathered from DHCP leases and ARP tables.
|
|
Only devices with active ARP entries are considered connected.
|
|
operationId: getDevices
|
|
responses:
|
|
'200':
|
|
description: List of connected devices
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ConnectedDevice'
|
|
example:
|
|
- name: "iPhone-12"
|
|
type: "mobile"
|
|
mac: "aa:bb:cc:11:22:33"
|
|
ip: "192.168.1.100"
|
|
- name: "MacBook-Pro"
|
|
type: "laptop"
|
|
mac: "dd:ee:ff:44:55:66"
|
|
ip: "192.168.1.101"
|
|
'500':
|
|
description: Failed to retrieve device list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/status:
|
|
get:
|
|
tags:
|
|
- System
|
|
summary: Get system status
|
|
description: |
|
|
Returns comprehensive system status including WiFi connection state,
|
|
hotspot status, connected device count, data usage, and uptime.
|
|
operationId: getStatus
|
|
responses:
|
|
'200':
|
|
description: Current system status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemStatus'
|
|
|
|
/api/logs:
|
|
get:
|
|
tags:
|
|
- Logs
|
|
summary: Get system logs
|
|
description: |
|
|
Returns the last 100 log entries from the system.
|
|
For real-time log streaming, use the WebSocket endpoint.
|
|
operationId: getLogs
|
|
responses:
|
|
'200':
|
|
description: List of log entries
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/LogEntry'
|
|
example:
|
|
- timestamp: "2025-10-28T14:32:10Z"
|
|
source: "WiFi"
|
|
message: "Scan terminé - 5 réseaux trouvés"
|
|
- timestamp: "2025-10-28T14:32:15Z"
|
|
source: "WiFi"
|
|
message: "Tentative de connexion à Hotel-Guest"
|
|
delete:
|
|
tags:
|
|
- Logs
|
|
summary: Clear system logs
|
|
description: Clears all stored log entries (keeps only the "logs cleared" entry)
|
|
operationId: clearLogs
|
|
responses:
|
|
'200':
|
|
description: Logs cleared successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SuccessResponse'
|
|
|
|
/ws/logs:
|
|
get:
|
|
tags:
|
|
- Logs
|
|
summary: WebSocket for real-time logs
|
|
description: |
|
|
WebSocket endpoint for receiving real-time log updates.
|
|
Upon connection, all existing logs are sent, followed by new logs as they occur.
|
|
|
|
This is a WebSocket endpoint - upgrade the HTTP connection to WebSocket protocol.
|
|
operationId: logsWebSocket
|
|
responses:
|
|
'101':
|
|
description: WebSocket connection established
|
|
'400':
|
|
description: WebSocket upgrade failed
|
|
|
|
components:
|
|
schemas:
|
|
WiFiNetwork:
|
|
type: object
|
|
description: Discovered WiFi network information
|
|
properties:
|
|
ssid:
|
|
type: string
|
|
description: Network SSID (name)
|
|
example: "Hotel-Guest"
|
|
signal:
|
|
type: integer
|
|
description: Signal strength (1-5 scale)
|
|
minimum: 1
|
|
maximum: 5
|
|
example: 4
|
|
security:
|
|
type: string
|
|
description: Security type
|
|
enum:
|
|
- Open
|
|
- WEP
|
|
- WPA
|
|
- WPA2
|
|
example: "WPA2"
|
|
channel:
|
|
type: integer
|
|
description: WiFi channel number
|
|
minimum: 1
|
|
maximum: 165
|
|
example: 6
|
|
bssid:
|
|
type: string
|
|
description: Access point MAC address
|
|
pattern: '^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$'
|
|
example: "aa:bb:cc:dd:ee:ff"
|
|
required:
|
|
- ssid
|
|
- signal
|
|
- security
|
|
- channel
|
|
- bssid
|
|
|
|
WiFiConnectRequest:
|
|
type: object
|
|
description: Request to connect to a WiFi network
|
|
properties:
|
|
ssid:
|
|
type: string
|
|
description: Network SSID to connect to
|
|
example: "Hotel-Guest"
|
|
password:
|
|
type: string
|
|
description: Network password (empty string for open networks)
|
|
example: "guest1234"
|
|
required:
|
|
- ssid
|
|
- password
|
|
|
|
HotspotConfig:
|
|
type: object
|
|
description: Hotspot (access point) configuration
|
|
properties:
|
|
ssid:
|
|
type: string
|
|
description: Hotspot SSID (network name)
|
|
minLength: 1
|
|
maxLength: 32
|
|
example: "TravelRouter"
|
|
password:
|
|
type: string
|
|
description: WPA2 password (minimum 8 characters)
|
|
minLength: 8
|
|
maxLength: 63
|
|
example: "secure123"
|
|
channel:
|
|
type: integer
|
|
description: WiFi channel (1-11 for 2.4GHz)
|
|
minimum: 1
|
|
maximum: 14
|
|
example: 6
|
|
required:
|
|
- ssid
|
|
- password
|
|
- channel
|
|
|
|
ConnectedDevice:
|
|
type: object
|
|
description: Device connected to the hotspot
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Device hostname
|
|
example: "iPhone-12"
|
|
type:
|
|
type: string
|
|
description: Detected device type
|
|
enum:
|
|
- mobile
|
|
- tablet
|
|
- laptop
|
|
- desktop
|
|
- unknown
|
|
example: "mobile"
|
|
mac:
|
|
type: string
|
|
description: Device MAC address
|
|
pattern: '^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$'
|
|
example: "aa:bb:cc:11:22:33"
|
|
ip:
|
|
type: string
|
|
description: Assigned IP address
|
|
pattern: '^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$'
|
|
example: "192.168.1.100"
|
|
required:
|
|
- name
|
|
- type
|
|
- mac
|
|
- ip
|
|
|
|
SystemStatus:
|
|
type: object
|
|
description: Overall system status
|
|
properties:
|
|
connected:
|
|
type: boolean
|
|
description: Whether router is connected to upstream WiFi
|
|
example: true
|
|
connectedSSID:
|
|
type: string
|
|
description: SSID of connected upstream network (empty if not connected)
|
|
example: "Hotel-Guest"
|
|
hotspotEnabled:
|
|
type: boolean
|
|
description: Whether the hotspot is currently enabled
|
|
example: true
|
|
connectedCount:
|
|
type: integer
|
|
description: Number of devices connected to hotspot
|
|
minimum: 0
|
|
example: 3
|
|
dataUsage:
|
|
type: number
|
|
format: double
|
|
description: Total data usage in MB (placeholder for future implementation)
|
|
example: 145.7
|
|
uptime:
|
|
type: integer
|
|
format: int64
|
|
description: System uptime in seconds
|
|
example: 3600
|
|
connectedDevices:
|
|
type: array
|
|
description: List of devices connected to hotspot
|
|
items:
|
|
$ref: '#/components/schemas/ConnectedDevice'
|
|
required:
|
|
- connected
|
|
- connectedSSID
|
|
- hotspotEnabled
|
|
- connectedCount
|
|
- dataUsage
|
|
- uptime
|
|
- connectedDevices
|
|
|
|
LogEntry:
|
|
type: object
|
|
description: System log entry
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: When the log entry was created
|
|
example: "2025-10-28T14:32:10Z"
|
|
source:
|
|
type: string
|
|
description: Log source component
|
|
enum:
|
|
- Système
|
|
- WiFi
|
|
- Hotspot
|
|
example: "WiFi"
|
|
message:
|
|
type: string
|
|
description: Log message
|
|
example: "Scan terminé - 5 réseaux trouvés"
|
|
required:
|
|
- timestamp
|
|
- source
|
|
- message
|
|
|
|
SuccessResponse:
|
|
type: object
|
|
description: Generic success response
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum:
|
|
- success
|
|
example: "success"
|
|
required:
|
|
- status
|
|
|
|
Error:
|
|
type: object
|
|
description: Error response
|
|
properties:
|
|
error:
|
|
type: string
|
|
description: Error message
|
|
example: "Erreur lors du scan WiFi"
|
|
required:
|
|
- error
|