Add OpenAPI specs

openapi.yaml

@@ -0,0 +1,523 @@
+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