Add openapi support

[Maschga]

My suggestion to fix #660.

Hi,
dieser PR soll die Dokumentation der REST-API mittels OpenAPI verbessern.
Gerne mal ausprobieren und gegebenenfalls Feedback geben.
~Maschga

[naltatis]

Ich find die Idee gut. Das natürlich nicht optimal ist ist die redundante Pflege. Aber das ist beim heutigen Ansatz auch bereits der Fall.

Pflege: Schön wäre natürlich, wenn die Beschreibungsdatei gleich aus dem Hauptprojekt generiert werden könnte. Sehe hier aber auch keinen guten Weg, wie wir das machen können ohne die https://github.com/evcc-io/evcc/blob/master/server/http.go komplett umzubauen oder aufzublähen. Daher würde ich sagen, dass wir erst einmal mit der separaten Pflege (AI assisted) starten können. Die müssen wir dann halt bei API Änderungen auf dem Zettel haben.

Übersetzung: Aktuell übersetzen wir alle Dokuseiten auch ins Englisch. Deutsch ist die Quelle. Hier würde ich um den Aufwand nicht zu groß werden zu lassen auf English-only gehen. Also direkt Englisch in der Quelle pflegen und keine Übersetzung machen. So ist es ja aktuell schon umgesetzt.

Darstellung: Damit bin ich aktuell noch unglücklich. Für mich stimmt hier die Signal-to-Noice Ratio nicht. Um einen Überblick über die API zu bekommen muss man viele klicken weil alles auf Einzelseiten verteilt ist. Der eigentliche Inhalt jeder Einzelseite ist sehr klein (URL/Params/Response). Navi und Seitenleiste (Codegen, Try, ...) nehmen den größten Raum ein. Alles auf einer Seite oder gruppiert nach Themen (Site, Ladepunkt, Fahrzeug, ...) fand ich übersichtlicher. Hab aber auf die Schnelle bei dem Plugin nicht gefunden ob/wie das geht. Den Codegen und Ausprobierbereich sind nett, aber für mich nicht essentiell. Heißt falls wir ein anderes Markdown Generierungstool finden was das ggf. nicht hat wäre das auch eine Option. Klare Darstellung der Parameter, kurze Beschreibung und beispielhafte Responsestruktur find ich wichtig.

[Maschga]

Redundante Pflege: Ihr habt sehr wenige API-Endpoints und Änderungen daran gibt es selten. Wenn die OpenAPI-Datei schlau aufgebaut ist, ist das manuelle Ändern der Dokumentation nicht mehr viel Aufwand. Da kann ich auch anbieten, dass ich immer die OpenAPI aktualisiere, wenn es an den Endpoints Änderungen gibt. Müsst mich dann nur benachrichtigen, zum Beispiel mit einem Issue in diesem Repo oder einem Ping.

Pflege: Ich habe einmal bei einem anderen Projekt versucht, die Dokumentation aus dem Code heraus zu generieren. Das macht bei hunderten an Endpoints auch Sinn, aber hier würde das den Code nur deutlich schlechter lesbarer machen. Deshalb rate ich in diesem Fall davon ab.

Übersetzung: Macht es Sinn, sowas auf Weblate zu verlegen?

Darstellung:

Alles auf einer Seite oder gruppiert nach Themen (Site, Ladepunkt, Fahrzeug, ...) fand ich übersichtlicher.

Ja, das finde ich auch. Aber dafür war die Dokumentation nicht sehr detailliert.
Ein Kompromiss wäre die Endpoints nach den Tags (Site, Loadpoint, ...) zu gruppieren, sodass die Navigation wie in dieser Demo aussieht: Für jeden Tag (Site, Ladepunkt, Fahrzeug, ...) wird ein aufklappbares Navigationsitem erstellt und darunter werden die jeweiligen Endpoints angezeigt. Das wird derzeit noch nicht für Dokumentationen unterstützt, die die Markdown-Dateien (wie auch in unserem Fall) automatisch anhand der Dateistruktur erstellen (siehe PaloAltoNetworks/docusaurus-openapi-docs#418 (comment)). Ich gehe aber davon aus, dass ich dieses Feature per PR hinzufügen kann.

Hab aber auf die Schnelle bei dem Plugin nicht gefunden ob/wie das geht. [...] Heißt falls wir ein anderes Markdown Generierungstool finden was das ggf. nicht hat wäre das auch eine Option.

Andere Plugins für Docusaurus und OpenAPI habe ich nicht gefunden. Generell habe ich auf der Suche danach, das Ökosystem von Docusaurus als eher klein wargenommen. Es gibt insgesamt nicht viele Plugins.
Habe auch einmal geschaut, ob es eine ähnliche Spezifikation wie OpenAPI für die MQTT-API geben würde und bin auf AsyncAPI gestoßen (was super ist), aber das einzige Plugin dafür ist dieser Fork mit schlechter Dokumentation: https://github.com/jpitlor/docusaurus-preset-asyncapi.
Was ich damit sagen will: Wenn wir die API mit OpenAPI dokumentieren wollen, haben wir nicht viele Optionen.

[naltatis]

@Maschga du könntest den Suchradius auch auf außerhalb des Docusaurus Ökosystems erweitern. Unsere cli Dokumentation generieren wir auch automatisch. Die ist nicht Docosaurus spezifisch sondern produziert einfach eine Markdown Struktur. Heißt, wenn wir ein gutes OpenAPI zu Markdown Plugin finden würde das ggf. auch schon reichen. Damit gehen natürlich "fancy feature" wie das interaktive Testen nicht, aber das wäre ja nicht so schlimm.