feat: task manager endpoint, updated documentation
This commit is contained in:
201
api/README.md
Normal file
201
api/README.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# SPORE API Documentation
|
||||
|
||||
This folder contains the OpenAPI specification for the SPORE embedded system API.
|
||||
|
||||
## Files
|
||||
|
||||
- **`openapi.yaml`** - OpenAPI 3.0 specification file
|
||||
- **`README.md`** - This documentation file
|
||||
|
||||
## OpenAPI Specification
|
||||
|
||||
The `openapi.yaml` file provides a complete, machine-readable specification of the SPORE API. It can be used with various tools to:
|
||||
|
||||
- Generate client libraries in multiple programming languages
|
||||
- Create interactive API documentation
|
||||
- Validate API requests and responses
|
||||
- Generate mock servers for testing
|
||||
- Integrate with API management platforms
|
||||
|
||||
## Using the OpenAPI Specification
|
||||
|
||||
### 1. View Interactive Documentation
|
||||
|
||||
#### Option A: Swagger UI Online
|
||||
1. Go to [Swagger Editor](https://editor.swagger.io/)
|
||||
2. Copy and paste the contents of `openapi.yaml`
|
||||
3. View the interactive documentation
|
||||
|
||||
#### Option B: Local Swagger UI
|
||||
```bash
|
||||
# Install Swagger UI locally
|
||||
npm install -g swagger-ui-express
|
||||
|
||||
# Or use Docker
|
||||
docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.yaml -v $(pwd):/swagger swaggerapi/swagger-ui
|
||||
```
|
||||
|
||||
### 2. Generate Client Libraries
|
||||
|
||||
#### Using OpenAPI Generator
|
||||
```bash
|
||||
# Install OpenAPI Generator
|
||||
npm install @openapitools/openapi-generator-cli -g
|
||||
|
||||
# Generate Python client
|
||||
openapi-generator generate -i openapi.yaml -g python -o python-client
|
||||
|
||||
# Generate JavaScript client
|
||||
openapi-generator generate -i openapi.yaml -g javascript -o js-client
|
||||
|
||||
# Generate C# client
|
||||
openapi-generator generate -i openapi.yaml -g csharp -o csharp-client
|
||||
```
|
||||
|
||||
#### Using Swagger Codegen
|
||||
```bash
|
||||
# Install Swagger Codegen
|
||||
npm install -g swagger-codegen
|
||||
|
||||
# Generate Python client
|
||||
swagger-codegen generate -i openapi.yaml -l python -o python-client
|
||||
|
||||
# Generate Java client
|
||||
swagger-codegen generate -i openapi.yaml -l java -o java-client
|
||||
```
|
||||
|
||||
### 3. Validate API Responses
|
||||
|
||||
#### Using OpenAPI Validator
|
||||
```bash
|
||||
# Install OpenAPI validator
|
||||
npm install -g @apidevtools/swagger-parser
|
||||
|
||||
# Validate the specification
|
||||
swagger-parser validate openapi.yaml
|
||||
```
|
||||
|
||||
### 4. Generate Mock Server
|
||||
|
||||
#### Using Prism (Stoplight)
|
||||
```bash
|
||||
# Install Prism
|
||||
npm install -g @stoplight/prism-cli
|
||||
|
||||
# Start mock server
|
||||
prism mock openapi.yaml
|
||||
|
||||
# The mock server will be available at http://localhost:4010
|
||||
```
|
||||
|
||||
## API Endpoints Overview
|
||||
|
||||
The SPORE API provides the following main categories of endpoints:
|
||||
|
||||
### Task Management
|
||||
- **`GET /api/tasks/status`** - Get comprehensive task status
|
||||
- **`POST /api/tasks/control`** - Control individual tasks
|
||||
|
||||
### System Status
|
||||
- **`GET /api/node/status`** - Get system resource information
|
||||
- **`GET /api/cluster/members`** - Get cluster membership
|
||||
|
||||
### System Management
|
||||
- **`POST /api/node/update`** - Handle OTA firmware updates
|
||||
- **`POST /api/node/restart`** - Trigger system restart
|
||||
|
||||
## Data Models
|
||||
|
||||
The OpenAPI specification includes comprehensive schemas for:
|
||||
|
||||
- **Task Information**: Task status, configuration, and execution details
|
||||
- **System Resources**: Memory usage, chip information, and performance metrics
|
||||
- **Cluster Management**: Node health, network topology, and resource sharing
|
||||
- **API Responses**: Standardized response formats and error handling
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Task Status Check
|
||||
```bash
|
||||
curl -s http://192.168.1.100/api/tasks/status | jq '.'
|
||||
```
|
||||
|
||||
### Task Control
|
||||
```bash
|
||||
# Disable a task
|
||||
curl -X POST http://192.168.1.100/api/tasks/control \
|
||||
-d "task=heartbeat&action=disable"
|
||||
|
||||
# Get detailed status
|
||||
curl -X POST http://192.168.1.100/api/tasks/control \
|
||||
-d "task=discovery_send&action=status"
|
||||
```
|
||||
|
||||
### System Monitoring
|
||||
```bash
|
||||
# Check system resources
|
||||
curl -s http://192.168.1.100/api/node/status | jq '.freeHeap'
|
||||
|
||||
# Monitor cluster health
|
||||
curl -s http://192.168.1.100/api/cluster/members | jq '.members[].status'
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Python Client
|
||||
```python
|
||||
import requests
|
||||
|
||||
# Get task status
|
||||
response = requests.get('http://192.168.1.100/api/tasks/status')
|
||||
tasks = response.json()
|
||||
|
||||
# Check active tasks
|
||||
active_count = tasks['summary']['activeTasks']
|
||||
print(f"Active tasks: {active_count}")
|
||||
|
||||
# Control a task
|
||||
control_data = {'task': 'heartbeat', 'action': 'disable'}
|
||||
response = requests.post('http://192.168.1.100/api/tasks/control', data=control_data)
|
||||
```
|
||||
|
||||
### JavaScript Client
|
||||
```javascript
|
||||
// Get task status
|
||||
fetch('http://192.168.1.100/api/tasks/status')
|
||||
.then(response => response.json())
|
||||
.then(data => {
|
||||
console.log(`Total tasks: ${data.summary.totalTasks}`);
|
||||
console.log(`Active tasks: ${data.summary.activeTasks}`);
|
||||
});
|
||||
|
||||
// Control a task
|
||||
fetch('http://192.168.1.100/api/tasks/control', {
|
||||
method: 'POST',
|
||||
headers: {'Content-Type': 'application/x-www-form-urlencoded'},
|
||||
body: 'task=heartbeat&action=disable'
|
||||
});
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new API endpoints or modifying existing ones:
|
||||
|
||||
1. Update the `openapi.yaml` file
|
||||
2. Add appropriate schemas for new data models
|
||||
3. Include example responses
|
||||
4. Update this README if needed
|
||||
5. Test the specification with validation tools
|
||||
|
||||
## Tools and Resources
|
||||
|
||||
- [OpenAPI Specification](https://swagger.io/specification/)
|
||||
- [OpenAPI Generator](https://openapi-generator.tech/)
|
||||
- [Swagger Codegen](https://github.com/swagger-api/swagger-codegen)
|
||||
- [Swagger UI](https://swagger.io/tools/swagger-ui/)
|
||||
- [Prism Mock Server](https://stoplight.io/open-source/prism/)
|
||||
- [OpenAPI Validator](https://apitools.dev/swagger-parser/)
|
||||
|
||||
## License
|
||||
|
||||
This API specification is part of the SPORE project and follows the same license terms.
|
||||
673
api/openapi.yaml
Normal file
673
api/openapi.yaml
Normal file
@@ -0,0 +1,673 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: SPORE Embedded System API
|
||||
description: |
|
||||
RESTful API for monitoring and controlling the SPORE embedded system.
|
||||
|
||||
The SPORE system provides comprehensive task management, system monitoring,
|
||||
and cluster management capabilities for ESP8266-based embedded devices.
|
||||
|
||||
## Features
|
||||
- **Task Management**: Monitor and control background tasks
|
||||
- **System Monitoring**: Real-time system resource tracking
|
||||
- **Cluster Management**: Multi-node cluster coordination
|
||||
- **OTA Updates**: Over-the-air firmware updates
|
||||
- **Health Monitoring**: System and task health metrics
|
||||
|
||||
## Authentication
|
||||
Currently, no authentication is required. All endpoints are accessible
|
||||
from the local network.
|
||||
|
||||
## Rate Limiting
|
||||
No rate limiting is currently implemented. Use responsibly.
|
||||
|
||||
## Base URL
|
||||
The API is accessible at `http://{device-ip}/` where `{device-ip}` is
|
||||
the IP address of your SPORE device on the local network.
|
||||
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: SPORE Development Team
|
||||
url: https://git.dcentral.systems/iot/spore
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
|
||||
servers:
|
||||
- url: http://{device-ip}
|
||||
description: Local SPORE device
|
||||
variables:
|
||||
device-ip:
|
||||
description: IP address of your SPORE device
|
||||
default: "10.0.1.60"
|
||||
|
||||
paths:
|
||||
/api/tasks/status:
|
||||
get:
|
||||
summary: Get comprehensive task status
|
||||
description: |
|
||||
Returns detailed status information for all registered tasks,
|
||||
including system resource metrics and task execution details.
|
||||
|
||||
This endpoint provides a complete overview of the system's
|
||||
task management status and can be used for monitoring and
|
||||
debugging purposes.
|
||||
|
||||
tags:
|
||||
- Task Management
|
||||
|
||||
responses:
|
||||
'200':
|
||||
description: Task status retrieved successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TaskStatusResponse'
|
||||
examples:
|
||||
default:
|
||||
summary: Default response
|
||||
value:
|
||||
summary:
|
||||
totalTasks: 6
|
||||
activeTasks: 5
|
||||
tasks:
|
||||
- name: "discovery_send"
|
||||
interval: 1000
|
||||
enabled: true
|
||||
running: true
|
||||
autoStart: true
|
||||
- name: "heartbeat"
|
||||
interval: 2000
|
||||
enabled: true
|
||||
running: true
|
||||
autoStart: true
|
||||
- name: "status_update"
|
||||
interval: 1000
|
||||
enabled: true
|
||||
running: true
|
||||
autoStart: true
|
||||
system:
|
||||
freeHeap: 48748
|
||||
uptime: 12345
|
||||
|
||||
'500':
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/api/tasks/control:
|
||||
post:
|
||||
summary: Control individual task operations
|
||||
description: |
|
||||
Controls the execution state of individual tasks. Supports
|
||||
enabling, disabling, starting, stopping, and getting detailed
|
||||
status for specific tasks.
|
||||
|
||||
This endpoint is useful for dynamic task management without
|
||||
requiring system restarts.
|
||||
|
||||
tags:
|
||||
- Task Management
|
||||
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- task
|
||||
- action
|
||||
properties:
|
||||
task:
|
||||
type: string
|
||||
description: Name of the task to control
|
||||
example: "heartbeat"
|
||||
action:
|
||||
type: string
|
||||
description: Action to perform on the task
|
||||
enum: [enable, disable, start, stop, status]
|
||||
example: "disable"
|
||||
|
||||
responses:
|
||||
'200':
|
||||
description: Task operation completed successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/TaskControlResponse'
|
||||
- $ref: '#/components/schemas/TaskStatusDetailResponse'
|
||||
examples:
|
||||
enable:
|
||||
summary: Task enabled
|
||||
value:
|
||||
success: true
|
||||
message: "Task enabled"
|
||||
task: "heartbeat"
|
||||
action: "enable"
|
||||
status:
|
||||
summary: Task status retrieved
|
||||
value:
|
||||
success: true
|
||||
message: "Task status retrieved"
|
||||
task: "discovery_send"
|
||||
action: "status"
|
||||
taskDetails:
|
||||
name: "discovery_send"
|
||||
enabled: true
|
||||
running: true
|
||||
interval: 1000
|
||||
system:
|
||||
freeHeap: 48748
|
||||
uptime: 12345
|
||||
|
||||
'400':
|
||||
description: Bad request - invalid parameters or action
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
missing_params:
|
||||
summary: Missing required parameters
|
||||
value:
|
||||
success: false
|
||||
message: "Missing parameters. Required: task, action"
|
||||
example: "{\"task\": \"discovery_send\", \"action\": \"status\"}"
|
||||
invalid_action:
|
||||
summary: Invalid action specified
|
||||
value:
|
||||
success: false
|
||||
message: "Invalid action. Use: enable, disable, start, stop, or status"
|
||||
task: "heartbeat"
|
||||
action: "invalid_action"
|
||||
|
||||
/api/node/status:
|
||||
get:
|
||||
summary: Get system status and API information
|
||||
description: |
|
||||
Returns comprehensive system resource information including
|
||||
memory usage, chip details, and a registry of all available
|
||||
API endpoints.
|
||||
|
||||
tags:
|
||||
- System Status
|
||||
|
||||
responses:
|
||||
'200':
|
||||
description: System status retrieved successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SystemStatusResponse'
|
||||
examples:
|
||||
default:
|
||||
summary: Default response
|
||||
value:
|
||||
freeHeap: 48748
|
||||
chipId: 12345678
|
||||
sdkVersion: "3.1.2"
|
||||
cpuFreqMHz: 80
|
||||
flashChipSize: 1048576
|
||||
api:
|
||||
- uri: "/api/node/status"
|
||||
method: 1
|
||||
- uri: "/api/tasks/status"
|
||||
method: 1
|
||||
- uri: "/api/tasks/control"
|
||||
method: 3
|
||||
|
||||
/api/cluster/members:
|
||||
get:
|
||||
summary: Get cluster membership information
|
||||
description: |
|
||||
Returns information about all nodes in the cluster,
|
||||
including their health status, resources, and API endpoints.
|
||||
|
||||
tags:
|
||||
- Cluster Management
|
||||
|
||||
responses:
|
||||
'200':
|
||||
description: Cluster information retrieved successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ClusterMembersResponse'
|
||||
examples:
|
||||
default:
|
||||
summary: Default response
|
||||
value:
|
||||
members:
|
||||
- hostname: "spore-node-1"
|
||||
ip: "192.168.1.100"
|
||||
lastSeen: 1234567890
|
||||
latency: 5
|
||||
status: "ACTIVE"
|
||||
resources:
|
||||
freeHeap: 48748
|
||||
chipId: 12345678
|
||||
sdkVersion: "3.1.2"
|
||||
cpuFreqMHz: 80
|
||||
flashChipSize: 1048576
|
||||
api:
|
||||
- uri: "/api/node/status"
|
||||
method: "GET"
|
||||
- uri: "/api/tasks/status"
|
||||
method: "GET"
|
||||
|
||||
/api/node/update:
|
||||
post:
|
||||
summary: Handle firmware update via OTA
|
||||
description: |
|
||||
Initiates an over-the-air firmware update. The firmware
|
||||
file should be uploaded as multipart/form-data.
|
||||
|
||||
tags:
|
||||
- System Management
|
||||
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
firmware:
|
||||
type: string
|
||||
format: binary
|
||||
description: Firmware binary file (.bin)
|
||||
|
||||
responses:
|
||||
'200':
|
||||
description: Firmware update initiated successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateResponse'
|
||||
examples:
|
||||
default:
|
||||
summary: Update initiated
|
||||
value:
|
||||
status: "updating"
|
||||
message: "Firmware update in progress"
|
||||
|
||||
'400':
|
||||
description: Invalid firmware file or update failed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/api/node/restart:
|
||||
post:
|
||||
summary: Restart the system
|
||||
description: |
|
||||
Triggers a system restart. The response will be sent
|
||||
before the restart occurs.
|
||||
|
||||
tags:
|
||||
- System Management
|
||||
|
||||
responses:
|
||||
'200':
|
||||
description: System restart initiated
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RestartResponse'
|
||||
examples:
|
||||
default:
|
||||
summary: Restart initiated
|
||||
value:
|
||||
status: "restarting"
|
||||
|
||||
components:
|
||||
schemas:
|
||||
TaskStatusResponse:
|
||||
type: object
|
||||
required:
|
||||
- summary
|
||||
- tasks
|
||||
- system
|
||||
properties:
|
||||
summary:
|
||||
$ref: '#/components/schemas/TaskSummary'
|
||||
tasks:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/TaskInfo'
|
||||
system:
|
||||
$ref: '#/components/schemas/SystemInfo'
|
||||
|
||||
TaskSummary:
|
||||
type: object
|
||||
required:
|
||||
- totalTasks
|
||||
- activeTasks
|
||||
properties:
|
||||
totalTasks:
|
||||
type: integer
|
||||
minimum: 0
|
||||
description: Total number of registered tasks
|
||||
example: 6
|
||||
activeTasks:
|
||||
type: integer
|
||||
minimum: 0
|
||||
description: Number of currently enabled tasks
|
||||
example: 5
|
||||
|
||||
TaskInfo:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- interval
|
||||
- enabled
|
||||
- running
|
||||
- autoStart
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Unique task identifier
|
||||
example: "discovery_send"
|
||||
interval:
|
||||
type: integer
|
||||
minimum: 1
|
||||
description: Execution frequency in milliseconds
|
||||
example: 1000
|
||||
enabled:
|
||||
type: boolean
|
||||
description: Whether task is currently enabled
|
||||
example: true
|
||||
running:
|
||||
type: boolean
|
||||
description: Whether task is actively executing
|
||||
example: true
|
||||
autoStart:
|
||||
type: boolean
|
||||
description: Whether task starts automatically
|
||||
example: true
|
||||
|
||||
SystemInfo:
|
||||
type: object
|
||||
required:
|
||||
- freeHeap
|
||||
- uptime
|
||||
properties:
|
||||
freeHeap:
|
||||
type: integer
|
||||
minimum: 0
|
||||
description: Available RAM in bytes
|
||||
example: 48748
|
||||
uptime:
|
||||
type: integer
|
||||
minimum: 0
|
||||
description: System uptime in milliseconds
|
||||
example: 12345
|
||||
|
||||
TaskControlResponse:
|
||||
type: object
|
||||
required:
|
||||
- success
|
||||
- message
|
||||
- task
|
||||
- action
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: Whether the operation was successful
|
||||
example: true
|
||||
message:
|
||||
type: string
|
||||
description: Human-readable operation result
|
||||
example: "Task enabled"
|
||||
task:
|
||||
type: string
|
||||
description: Name of the task that was operated on
|
||||
example: "heartbeat"
|
||||
action:
|
||||
type: string
|
||||
description: Action that was performed
|
||||
example: "enable"
|
||||
|
||||
TaskStatusDetailResponse:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/TaskControlResponse'
|
||||
- type: object
|
||||
required:
|
||||
- taskDetails
|
||||
properties:
|
||||
taskDetails:
|
||||
$ref: '#/components/schemas/TaskDetailInfo'
|
||||
|
||||
TaskDetailInfo:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- enabled
|
||||
- running
|
||||
- interval
|
||||
- system
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Task name
|
||||
example: "discovery_send"
|
||||
enabled:
|
||||
type: boolean
|
||||
description: Whether task is enabled
|
||||
example: true
|
||||
running:
|
||||
type: boolean
|
||||
description: Whether task is running
|
||||
example: true
|
||||
interval:
|
||||
type: integer
|
||||
description: Task execution interval
|
||||
example: 1000
|
||||
system:
|
||||
$ref: '#/components/schemas/SystemInfo'
|
||||
|
||||
SystemStatusResponse:
|
||||
type: object
|
||||
required:
|
||||
- freeHeap
|
||||
- chipId
|
||||
- sdkVersion
|
||||
- cpuFreqMHz
|
||||
- flashChipSize
|
||||
- api
|
||||
properties:
|
||||
freeHeap:
|
||||
type: integer
|
||||
description: Available RAM in bytes
|
||||
example: 48748
|
||||
chipId:
|
||||
type: integer
|
||||
description: ESP8266 chip ID
|
||||
example: 12345678
|
||||
sdkVersion:
|
||||
type: string
|
||||
description: ESP8266 SDK version
|
||||
example: "3.1.2"
|
||||
cpuFreqMHz:
|
||||
type: integer
|
||||
description: CPU frequency in MHz
|
||||
example: 80
|
||||
flashChipSize:
|
||||
type: integer
|
||||
description: Flash chip size in bytes
|
||||
example: 1048576
|
||||
api:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ApiEndpoint'
|
||||
|
||||
ApiEndpoint:
|
||||
type: object
|
||||
required:
|
||||
- uri
|
||||
- method
|
||||
properties:
|
||||
uri:
|
||||
type: string
|
||||
description: API endpoint URI
|
||||
example: "/api/node/status"
|
||||
method:
|
||||
type: integer
|
||||
description: HTTP method (1=GET, 3=POST)
|
||||
example: 1
|
||||
|
||||
ClusterMembersResponse:
|
||||
type: object
|
||||
required:
|
||||
- members
|
||||
properties:
|
||||
members:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ClusterNode'
|
||||
|
||||
ClusterNode:
|
||||
type: object
|
||||
required:
|
||||
- hostname
|
||||
- ip
|
||||
- lastSeen
|
||||
- latency
|
||||
- status
|
||||
- resources
|
||||
- api
|
||||
properties:
|
||||
hostname:
|
||||
type: string
|
||||
description: Node hostname
|
||||
example: "spore-node-1"
|
||||
ip:
|
||||
type: string
|
||||
format: ipv4
|
||||
description: Node IP address
|
||||
example: "192.168.1.100"
|
||||
lastSeen:
|
||||
type: integer
|
||||
description: Timestamp of last communication
|
||||
example: 1234567890
|
||||
latency:
|
||||
type: integer
|
||||
description: Network latency in milliseconds
|
||||
example: 5
|
||||
status:
|
||||
type: string
|
||||
enum: [ACTIVE, INACTIVE, DEAD]
|
||||
description: Node health status
|
||||
example: "ACTIVE"
|
||||
resources:
|
||||
$ref: '#/components/schemas/SystemResources'
|
||||
api:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/ApiEndpoint'
|
||||
|
||||
SystemResources:
|
||||
type: object
|
||||
required:
|
||||
- freeHeap
|
||||
- chipId
|
||||
- sdkVersion
|
||||
- cpuFreqMHz
|
||||
- flashChipSize
|
||||
properties:
|
||||
freeHeap:
|
||||
type: integer
|
||||
description: Available RAM in bytes
|
||||
example: 48748
|
||||
chipId:
|
||||
type: integer
|
||||
description: ESP8266 chip ID
|
||||
example: 12345678
|
||||
sdkVersion:
|
||||
type: string
|
||||
description: ESP8266 SDK version
|
||||
example: "3.1.2"
|
||||
cpuFreqMHz:
|
||||
type: integer
|
||||
description: CPU frequency in MHz
|
||||
example: 80
|
||||
flashChipSize:
|
||||
type: integer
|
||||
description: Flash chip size in bytes
|
||||
example: 1048576
|
||||
|
||||
UpdateResponse:
|
||||
type: object
|
||||
required:
|
||||
- status
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
enum: [updating, failed]
|
||||
description: Update operation status
|
||||
example: "updating"
|
||||
message:
|
||||
type: string
|
||||
description: Additional status information
|
||||
example: "Firmware update in progress"
|
||||
|
||||
RestartResponse:
|
||||
type: object
|
||||
required:
|
||||
- status
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
enum: [restarting]
|
||||
description: Restart operation status
|
||||
example: "restarting"
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required:
|
||||
- success
|
||||
- message
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
description: Always false for error responses
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
description: Error description
|
||||
example: "Missing parameters. Required: task, action"
|
||||
example:
|
||||
type: string
|
||||
description: Example of correct usage
|
||||
example: "{\"task\": \"discovery_send\", \"action\": \"status\"}"
|
||||
task:
|
||||
type: string
|
||||
description: Task name (if applicable)
|
||||
example: "heartbeat"
|
||||
action:
|
||||
type: string
|
||||
description: Action attempted (if applicable)
|
||||
example: "invalid_action"
|
||||
|
||||
securitySchemes:
|
||||
# Currently no authentication required
|
||||
# This section can be expanded when authentication is implemented
|
||||
|
||||
tags:
|
||||
- name: Task Management
|
||||
description: Operations for monitoring and controlling background tasks
|
||||
- name: System Status
|
||||
description: System resource monitoring and API information
|
||||
- name: Cluster Management
|
||||
description: Multi-node cluster coordination and health monitoring
|
||||
- name: System Management
|
||||
description: System-level operations like updates and restarts
|
||||
|
||||
externalDocs:
|
||||
description: SPORE Project Documentation
|
||||
url: https://github.com/your-org/spore
|
||||
Reference in New Issue
Block a user