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

• fix dark mode @naltatis
• fix DELETE error @naltatis
• fix error Failed to resolve $ref: $ref for "#/components/parameters/delay" (Zeilen 727 und 753) @naltatis

[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.

[naltatis]

@Maschga mir erschließt sich der Mehrwert von dem Build-Schritt (generateOpenApiFile) noch nicht. Ich seh dass da ein Description Feld erzeugt wird. Wenn das nicht zwingend erforderlich ist würde ich diese Indirektion gerne rausnehmen. Musste in der Tat selbst etwas suchen bis ich rausgefunden habe wieso meine Änderungen keinen Effekt haben :D

[Maschga]

In OpenApi kann man zu Schemas und zu Parametern eine Beschreibung hinzufügen. Oftmals sind diese Beschreibungen identisch. Außerdem sind die Schemas die Wurzel/Basis der Dokumentation. Es ist oft so, dass Parameter auf ein Schema referenzieren. Wenn auf ein Schema referenziert wird, wird aber nicht die Beschreibung des Schemas für die Parameter verwendet. Das macht das Skript: Es kopiert die Beschreibungen der Schemas zu den jeweiligen Parametern.

Sorry, dass du da so lange hast suchen müssen. 😅

[Maschga]

Wenn du die OpenApi ohne den Build Schritt anschauen möchtest, dann kopiere die openapi/rest-api.yaml in den static-Ordner.

[naltatis]

Das macht das Skript: Es kopiert die Beschreibungen der Schemas zu den jeweiligen Parametern.

Ah, das hab ich jetzt erst gelesen. Mit dem letzten Schritt hab ich die Transformation rausgenommen.

Hast du mal ein Beispiel was konkret jetzt nicht gezogen wird?

[Maschga]

Am Beispiel von dem Endpoint für wiederholende Pläne:

Vorher:

Nachher mit deinem letzten Commit:

=> Die Beschreibungen der Parameter sind verschwunden.

[Maschga]

Wenn ich einen DELETE-Endpoint aufrufe, gibt es noch einen Fehler: TypeError: NetworkError when attempting to fetch resource. Alle ENdpoints - bis auf die DELETE-Endpoints - funktonieren dafür.

[naltatis]

Es ist oft so, dass Parameter auf ein Schema referenzieren.

Ich würde dann die description lieber doppeln bzw. nur bei den Parametern machen. Da sind sie ja für die Benutzung am wichtigsten.

[Maschga]

Ist für mich in Ordnung. Dann müssen nur immer 12 Parameter extra behandelt werden.