Swagger UI (API Docs view)

The dashboard's API Docs tab embeds the auto-generated Swagger UI against the live OpenAPI spec — the same JSON FastAPI publishes at /openapi.json. Every endpoint the running build supports shows up here automatically; there's no static reference that drifts.

API Docs view — Swagger UI sidebar of endpoints grouped by router (Telemetry, Controls, Battery, Wind, Fuel Cell, Hybrid DC, OCPP, CSIP, Logs)

Opening it

The dashboard's left nav has an API Docs entry; it loads the embedded Swagger UI in the main pane. The standalone copy is at http://<host>:8111/docs if you want to bookmark it without going through the dashboard chrome.

For a static, printable reference, ReDoc lives at http://<host>:8111/redoc — same OpenAPI spec, different renderer.

What's auto-discovered

Every router included in app.py shows up grouped by its FastAPI tags field. The current groupings:

Group Source router
Core telemetry, overview, server-info, devices, history, commands
Controls grid, time, nameplate, configured-settings, stop
Grid Support volt-var, volt-watt, watt-var, freq-droop, PF
Battery /battery, /controls/battery
Wind /wind, /wind/override
Fuel Cell /fuelcell, /fuelcell/setpoint
Hybrid DC /hybrid-dc, /hybrid-dc/dispatch, /hybrid-dc/manual
EVSE / OCPP /evse/*, /evse/{id}/connectors/{cid}/*, /ocpp/{id}/*
CSIP Client /csip/*
SunSpec Client /sunspec-client/*
DC I/V /dc-iv

Each endpoint expands to show:

  • HTTP method + path + summary + description
  • Request body schema (with examples)
  • Query / path parameters
  • Per-status-code response schemas
  • The Try it out button that fills the request body with the schema's example, runs it against the live server, and shows the raw response

What's not in the Swagger UI

A handful of surfaces deliberately stay out of the OpenAPI spec:

  • /api/dersim/ws/telemetry — the WebSocket telemetry stream. OpenAPI 3.x doesn't model WebSocket streams cleanly, so the Swagger UI never shows it. See the WebSocket page for the connection lifecycle + payload shape.
  • /openapi.json itself — meta-endpoint, doesn't appear in its own list.
  • Static assets — /, /index.html, dashboard JS / CSS — none of these are in the spec because they're not API surface.

When to use Swagger UI vs the REST page

Use case Reach for
Schema reference for one endpoint Swagger UI — schemas + examples are right there
Trying a request interactively Swagger UI — "Try it out" runs against the live server
Browsing all endpoints at once REST API page — flat catalog table
Generating a typed client GET /openapi.json straight to openapi-generator
Embedding in CI / docs / scripts GET /openapi.json

The Swagger UI is the canonical interactive interface; the REST page is the canonical navigational one.