Stefan/evcc-io
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

API: generate /api/state documentation from UI types (#32431)

Browse source 
Co-authored-by: Michael Geers <michael@geers.tv>
This commit is contained in:
andig 2026-08-03 13:06:37 +02:00 • committed by GitHub
parent c7c744f54e
commit c3f3384bfc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
44 changed files with 8757 additions and 3347 deletions
Download patch file Download diff file Expand all files Collapse all files

8462
server/mcp/openapi.json
View file

File diff suppressed because it is too large Load diff

44
server/mcp/openapi.md
View file

@ -216,13 +216,13 @@ Directly controls the mode of all controllable batteries. evcc behavior like 'pr
| Name | Type | Description |
|------|------|-------------|
| batteryMode | string | Battery mode |
| batteryMode | string | Battery operation mode. |
**Example call:**
```json
call setExternalBatteryMode {
"batteryMode": "normal"
"batteryMode": "unknown"
}
```
@ -384,26 +384,6 @@ call setSolarAdjusted {
}
```
## getState
Returns the complete state of the system. This structure is used by the UI. It can be filtered by JQ to only return a subset of the data.
**Tags:** general
**Arguments:**
| Name | Type | Description |
|------|------|-------------|
| jq | string | Filter the state with JQ |
**Example call:**
```json
call getState {
"jq": "example"
}
```
## removeGlobalSmartCostLimit
Convenience method to remove limit for all loadpoints at once. Value is applied to each individual loadpoint.
@ -1166,6 +1146,26 @@ call updateSession {
}
```
## getState
Returns the complete state of the system. This structure is used by the UI and also published via websocket and MQTT. It can be filtered by JQ to only return a subset of the data. Note: the response mirrors the internal UI state and carries no compatibility promise. Fields may change or disappear between releases.
**Tags:** state
**Arguments:**
| Name | Type | Description |
|------|------|-------------|
| jq | string | Filter the state with JQ |
**Example call:**
```json
call getState {
"jq": "example"
}
```
## clearCache
Clears all cached data. This resets all cached values from tariffs, vehicle APIs, and other components that use caching.

3
server/openapi.go
View file

@ -1,4 +1,3 @@
package server
//go:generate go tool openapi openapi.yaml mcp/openapi.json
//go:generate go tool openapi-mcp --doc mcp/openapi.md openapi.yaml
//go:generate go tool openapi-mcp --doc mcp/openapi.md mcp/openapi.json

1829
server/openapi.state.yaml Normal file
View file

File diff suppressed because it is too large Load diff

111
server/openapi.yaml
View file

@ -8,6 +8,7 @@ info:
servers:
- url: https://demo.evcc.io/api
tags:
- name: state
- name: auth
- name: battery
- name: db
@ -449,7 +450,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/Mode"
$ref: "./openapi.state.yaml#/components/schemas/ChargeMode"
/loadpoints/{id}/phases/{phases}:
post:
operationId: setLoadpointPhases
@ -523,7 +524,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/StaticEnergyPlan"
$ref: "./openapi.state.yaml#/components/schemas/StaticEnergyPlan"
/loadpoints/{id}/plan/repeating/preview/{soc}/{weekdays}/{hourMinuteTime}/{timezone}:
get:
operationId: previewLoadpointRepeatingPlan
@ -590,14 +591,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/PlanStrategy"
$ref: "./openapi.state.yaml#/components/schemas/PlanStrategy"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/PlanStrategy"
$ref: "./openapi.state.yaml#/components/schemas/PlanStrategy"
/loadpoints/{id}/priority/{priority}:
post:
operationId: setLoadpointPriority
@ -947,11 +948,11 @@ paths:
get:
operationId: getState
summary: System state
description: "Returns the complete state of the system. This structure is used by the UI. It can be filtered by JQ to only return a subset of the data."
description: "Returns the complete state of the system. This structure is used by the UI and also published via websocket and MQTT. It can be filtered by JQ to only return a subset of the data. Note: the response mirrors the internal UI state and carries no compatibility promise. Fields may change or disappear between releases."
externalDocs:
url: https://docs.evcc.io/integrations/rest-api
tags:
- general
- state
parameters:
- name: jq
in: query
@ -971,7 +972,7 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/State"
$ref: "./openapi.state.yaml#/components/schemas/State"
/system/log:
get:
operationId: getSystemLogs
@ -1164,7 +1165,7 @@ paths:
type: object
properties:
mode:
$ref: "#/components/schemas/Mode"
$ref: "./openapi.state.yaml#/components/schemas/ChargeMode"
/vehicles/{name}/plan/repeating:
post:
operationId: updateVehicleRepeatingPlans
@ -1183,7 +1184,7 @@ paths:
schema:
type: array
items:
$ref: "#/components/schemas/RepeatingPlan"
$ref: "./openapi.state.yaml#/components/schemas/RepeatingPlan"
responses:
"200":
description: Success
@ -1192,7 +1193,7 @@ paths:
schema:
type: array
items:
$ref: "#/components/schemas/RepeatingPlan"
$ref: "./openapi.state.yaml#/components/schemas/RepeatingPlan"
/vehicles/{name}/plan/soc:
delete:
operationId: deleteVehicleSocPlan
@ -1248,14 +1249,14 @@ paths:
content:
application/json:
schema:
$ref: "#/components/schemas/PlanStrategy"
$ref: "./openapi.state.yaml#/components/schemas/PlanStrategy"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/PlanStrategy"
$ref: "./openapi.state.yaml#/components/schemas/PlanStrategy"
/db/backup:
get:
operationId: downloadBackup
@ -1433,16 +1434,6 @@ paths:
description: Invalid parameters or database offline
components:
schemas:
BatteryMode:
description: Battery mode
type: string
example: normal
enum:
- unknown
- normal
- hold
- charge
- holdcharge
ChangePassword:
type: object
properties:
@ -1580,14 +1571,6 @@ components:
- INFO
- DEBUG
- TRACE
Mode:
description: "Charging mode."
type: string
enum:
- "off"
- "now"
- "minpv"
- "pv"
Odometer:
nullable: true
type: "number"
@ -1626,51 +1609,10 @@ components:
type: integer
example: 3600
minimum: 0
Rate:
type: object
description: A charging interval
properties:
start:
description: Start
$ref: "#/components/schemas/Timestamp"
end:
description: End
$ref: "#/components/schemas/Timestamp"
value:
description: Cost
type: number
minimum: 0
Rates:
type: array
items:
$ref: "#/components/schemas/Rate"
PlanStrategy:
description: Charging plan strategy configuration
type: object
properties:
continuous:
description: "Force continuous planning"
type: boolean
precondition:
description: "Precondition duration in seconds"
type: integer
minimum: 0
RepeatingPlan:
externalDocs:
url: https://docs.evcc.io/en/features/plans#repeating-plans
type: object
properties:
active:
description: "Set plan active."
type: boolean
soc:
$ref: "#/components/schemas/Soc"
time:
$ref: "#/components/schemas/HourMinuteTime"
tz:
$ref: "#/components/schemas/IANATimeZone"
weekdays:
$ref: "#/components/schemas/Weekdays"
$ref: "./openapi.state.yaml#/components/schemas/Rate"
Soc:
description: SOC in %
type: number
@ -1682,27 +1624,6 @@ components:
type: number
example: 50
minimum: 0
State:
description: "The actual state structure is not documented yet. Most values should be self-explanatory. Note: While the overall structure is quite stable, details may change between releases."
type: object
StaticEnergyPlan:
externalDocs:
url: https://docs.evcc.io/en/features/plans#energy-amount-plan
type: object
properties:
energy:
$ref: "#/components/schemas/Energy"
time:
$ref: "#/components/schemas/Timestamp"
StaticSocPlan:
externalDocs:
url: https://docs.evcc.io/en/features/plans#create-charging-plan
type: object
properties:
soc:
$ref: "#/components/schemas/Soc"
time:
$ref: "#/components/schemas/Timestamp"
Timestamp:
description: Timestamp in RFC3339 format
type: string
@ -1799,7 +1720,7 @@ components:
in: path
required: true
schema:
$ref: "#/components/schemas/Mode"
$ref: "./openapi.state.yaml#/components/schemas/ChargeMode"
soc:
name: soc
description: SOC in %
@ -1861,7 +1782,7 @@ components:
in: path
required: true
schema:
$ref: "#/components/schemas/BatteryMode"
$ref: "./openapi.state.yaml#/components/schemas/BatteryMode"
costLimit:
name: cost
description: Cost limit in configured currency (default EUR) or CO2 limit in g/kWh

1
server/openapi_test.go
View file

@ -9,6 +9,7 @@ import (
func TestOpenAPIValidation(t *testing.T) {
loader := openapi3.NewLoader()
loader.IsExternalRefsAllowed = true
doc, err := loader.LoadFromFile("openapi.yaml")
require.NoError(t, err)
require.NoError(t, doc.Validate(loader.Context))