docs: add intelligence endpoints to OpenAPI spec
Add vendor-treemap, ssid-graph, and fingerprint-clusters paths with response schemas. Bump spec version to 0.1.4.
This commit is contained in:
user
@@ -2,7 +2,7 @@ openapi: 3.0.3
|
||||
info:
|
||||
title: ESP32-Web API
|
||||
description: REST API for ESP32 sensor fleet management
|
||||
version: 0.1.3
|
||||
version: 0.1.4
|
||||
contact:
|
||||
name: ESP32-Web
|
||||
servers:
|
||||
@@ -24,6 +24,8 @@ tags:
|
||||
description: Aggregate statistics
|
||||
- name: export
|
||||
description: Data export endpoints
|
||||
- name: intelligence
|
||||
description: Device intelligence and visualization data
|
||||
|
||||
paths:
|
||||
/sensors:
|
||||
@@ -556,6 +558,83 @@ paths:
|
||||
schema:
|
||||
type: string
|
||||
|
||||
/intelligence/vendor-treemap:
|
||||
get:
|
||||
tags: [intelligence]
|
||||
summary: Get vendor treemap hierarchy
|
||||
description: Returns D3-ready hierarchy of devices grouped by type (wifi/ble) and vendor.
|
||||
operationId: getVendorTreemap
|
||||
responses:
|
||||
'200':
|
||||
description: Treemap hierarchy
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/VendorTreemap'
|
||||
|
||||
/intelligence/ssid-graph:
|
||||
get:
|
||||
tags: [intelligence]
|
||||
summary: Get SSID social graph
|
||||
description: >
|
||||
Returns force-graph data with device nodes and links between devices
|
||||
that share probed SSIDs. Requires probe data (promiscuous mode).
|
||||
operationId: getSsidGraph
|
||||
parameters:
|
||||
- name: hours
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 24
|
||||
minimum: 1
|
||||
description: Time window in hours
|
||||
- name: min_shared
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
minimum: 1
|
||||
description: Minimum shared SSIDs to create a link
|
||||
- name: limit
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 200
|
||||
maximum: 500
|
||||
minimum: 1
|
||||
description: Max number of nodes (top by probe diversity)
|
||||
responses:
|
||||
'200':
|
||||
description: Force-graph data
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SsidGraph'
|
||||
|
||||
/intelligence/fingerprint-clusters:
|
||||
get:
|
||||
tags: [intelligence]
|
||||
summary: Get device fingerprint clusters
|
||||
description: >
|
||||
Groups active devices by behavior (device type, vendor, activity level).
|
||||
Uses rule-based clustering: low (<5), medium (5-20), high (>20) activity.
|
||||
operationId: getFingerprintClusters
|
||||
parameters:
|
||||
- name: hours
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 24
|
||||
minimum: 1
|
||||
description: Time window in hours
|
||||
responses:
|
||||
'200':
|
||||
description: Device clusters
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FingerprintClusters'
|
||||
|
||||
components:
|
||||
parameters:
|
||||
hostname:
|
||||
@@ -834,3 +913,128 @@ components:
|
||||
type: integer
|
||||
hours:
|
||||
type: integer
|
||||
|
||||
VendorTreemap:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: devices
|
||||
children:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: ble
|
||||
children:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: Apple, Inc.
|
||||
value:
|
||||
type: integer
|
||||
example: 42
|
||||
|
||||
SsidGraph:
|
||||
type: object
|
||||
properties:
|
||||
nodes:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Device MAC address
|
||||
device_id:
|
||||
type: integer
|
||||
vendor:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
enum: [wifi, ble]
|
||||
ssid_count:
|
||||
type: integer
|
||||
links:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
source:
|
||||
type: string
|
||||
description: Source device MAC
|
||||
target:
|
||||
type: string
|
||||
description: Target device MAC
|
||||
shared_ssids:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
weight:
|
||||
type: integer
|
||||
ssids:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
ssid:
|
||||
type: string
|
||||
device_count:
|
||||
type: integer
|
||||
|
||||
FingerprintClusters:
|
||||
type: object
|
||||
properties:
|
||||
clusters:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
label:
|
||||
type: string
|
||||
example: Apple BLE - High Activity
|
||||
device_type:
|
||||
type: string
|
||||
enum: [wifi, ble]
|
||||
vendor:
|
||||
type: string
|
||||
activity:
|
||||
type: string
|
||||
enum: [Low, Medium, High]
|
||||
device_count:
|
||||
type: integer
|
||||
devices:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
mac:
|
||||
type: string
|
||||
probe_count:
|
||||
type: integer
|
||||
sighting_count:
|
||||
type: integer
|
||||
avg_rssi:
|
||||
type: integer
|
||||
nullable: true
|
||||
centroid:
|
||||
type: object
|
||||
properties:
|
||||
probe_rate:
|
||||
type: number
|
||||
sighting_rate:
|
||||
type: number
|
||||
avg_rssi:
|
||||
type: integer
|
||||
nullable: true
|
||||
total_devices:
|
||||
type: integer
|
||||
total_clusters:
|
||||
type: integer
|
||||
|
||||
Reference in New Issue
Block a user