Add AsyncAPI support

[Maschga]

Fix #714
Fix #666

TODO:

• write AsyncAPI specification
• recheck types
• add examples
• complete enums
• replace TODOs
• Theming @naltatis
• document:
  • Benachrichtigungen
  • InfluxDB
  • EEBus
  • Lastmanagement
  • Modbus-Proxy
  • HEMS
  • auxPower, auxMeter
  • ext

Preview:

[Maschga]

@naltatis Ich bin soweit durch. Du kannst gerne starten. Wenn du Fragen hast, immer her damit.

Es sind 304 TODOs übrig, sorry für den kleinen Schock.
Teilweise lässt sich aber die Beschreibung von der RestAPi verwenden und bestimmt lassen sich manche TODOs auch einfach löschen.

[naltatis]

Was macht diese Datei denn hier? Vmtl. zu Entwicklungszwecken rüberkopiert, oder?

[Maschga]

Ja, das ist für Entwicklungszwecke, bin daran die Setter abgegangen. Die Datei sollte hier nicht sein.

[naltatis]

Ich überlege immer noch ob wir die Daten nicht direkt aus der State Typescript Struktur + optionale JsDoc Annotation im Core Projekt erzeugen sollten. Vielleicht auch erst einmal ohne AsyncAPI Format sondern direkt als Markdown (oder leichtes JSON-Meta-Format) ähnlich wie die aktuelle Doku nur autogeneriert/-aktualisiert.

Also aus einer Struktur wie dieser

// types.ts
export interface State {
  battery: Battery[];
  /** @mqtt.action write */
  batteryMode: BatteryMode;
  ...
}

interface Battery {
  power: number;
  capacity: number;
  soc: number;
  /** @description battery control supported */
  controllable: boolean
}

...

Dann so etwas generieren

# MQTT Docs

- `/battery/<index>/power` number
- `/battery/<index>/capacity ` number
- `/battery/<index>/soc` number
- `/battery/<index>/controllable` battery control supported, boolean
- `/batteryMode` ["ModeA", "ModeB"], writable

Natürlich wäre es cool, wenn wir Beschreibungstexte zu allen Werte hätten, wäre aber für einen ersten Wurf nicht zwingend erforderlich.

Wir können auch noch mit Value-Types anstatt JS Primitiven Arbeiten (bspw. capacity: Energy) und dann am Value Type Dokumentieren, dass es Energy in kWh, number ist weil wir das immer konsistent verwenden. Aber alles potentielle Erweiterung. Könnte man dann iterativ immer schicker machen.

Hierfür müssten am Parser/Generator bauen, die dann das Markdown (oder ein JSON) erzeugen welches wird dann bei jedem Release vom Core Repo ins Docs Repo pushen. Bei den Templates machen wir das heute ja schon so ähnlich. Defacto bauen wir dann dort die Publish Logik von unserem Go Code nach. Aber die ändert sich weniger häufig als sich Felder verändern.

[Maschga]

Soetwas habe ich mir auch schon gedacht.
DIe mqtt-API ist viel zu groß und undurchsichtig, um sie manuell zu dokumentieren und danach zu aktualiseren.

Dann machen wir ertseinmal den Typescript Rewrite und dann das MQTT-API Thema. 👍