Verwendung von Schemas in openapi.json

hbuerger

Ja, die OpenAPI Spec bezieht sich auf die standard Einstellungen von ChurchTools. Das jede CT Installation eigene DB Felder einstellen kann macht sehr viele Dinge komplizierter. Eine automatische API Spec für jede Installation ist technisch sicherlich irgendwie möglich, aber das sprengt gerade etwas den Rahmen. Der Mehrwert ist in meinen Augen doch eher geringer.

Ich verstehe es, dass man gerne alle Felder in seiner Client Lib haben will, aber selbst dann müsste jeder seine eigene erstellen und dass das passiert halte ich eher für unwahrscheinlich.

Zudem, eine gute Lib ermöglicht immer Zugriff auf die Raw Response. Also ich denke es nicht nicht zwingend notwendig Methoden für alle Felder zu implementieren.

Wenn du aber hier Ideen hast / Motivation solch eine Implementierung umzusetzen mit uns, dann melde dich gerne.

eppjo

@aschild woher hast du die openapi.yaml? Es wird doch nur die json angeboten.

aschild

@eppjo sagte in Verwendung von Schemas in openapi.json:

@aschild woher hast du die openapi.yaml? Es wird doch nur die json angeboten.

https://<instanz>/docs/openApi/openapi.yaml

Und dann sind die alle miteinander verlinkt.
Wenn du es selbst hostest geht's einfacher um alles abzurufen und dann zu einer Datei zusammenzusetzen

hbuerger

Ich würde empfehlen immer die .json Datei zu nehmen, die alles enthält. Wir stellen intern gerade die YAML Datei Struktur etwas um, um die API leichter pflegen zu können. Sprich, wenn du dich auf die YAML Dateien verlässt, kann es sein, dass die in späteren Versionen ganz anders aussehen. Das generierte JSON ist immer ähnlich.

aschild

@hbuerger sagte in Verwendung von Schemas in openapi.json:

Ich würde empfehlen immer die .json Datei zu nehmen, die alles enthält. Wir stellen intern gerade die YAML Datei Struktur etwas um, um die API leichter pflegen zu können. Sprich, wenn du dich auf die YAML Dateien verlässt, kann es sein, dass die in späteren Versionen ganz anders aussehen. Das generierte JSON ist immer ähnlich.

Ja, das ist sicher zu empfehlen.
Nur ist die aktuelle json Datei nicht wirklich richtig zusammengsetzt, aber das Problem ist ja bei euch bekannt

eppjo

Also ich habe die json heruntergeladen um mir einen Java Client zu generieren. Dazu auf editor.swagger.io den Inhalt einfügen, es wird gefragt, ob nach yaml konvertiert werden soll.
Und es werden auch gleich Fehler angezeigt.
Z.B. bool statt boolean, int statt integer, required wo es nicht hingehörte. Evtl falsche Verwendung von oneOf?

Erst nach dem fixen bekam ich meinen generierten Client.

Der generierte Client hatte einige definierte Entitäten, doch viel mehr anonyme Inline Entitäten, deren Namen sich bei jeder Generierung ändern können und somit die Verwendung unbrauchbar machen. Hier wäre es ratsam auf definierte Entitäten zu referenzieren.
Zum anderen sind z.T. Datums Felder definiert, obwohl ein date-time zurück geschickt wird, und das noch nicht mal im ISO Format, was wiederum dem unmarshalling nicht schmeckte und mich zum aufgeben brachte
Getestet habe ich die Event Api.

Ich weiß aber auch nicht wie der Reifegrad dieser API ist. Es war eben ein Schnelltest.

aschild

@eppjo Ja, die openapi.json ist von den Entitäten her nicht brauchbar, das es für jeden Request/Parameterversion eigene Entitäten erstellt.
Wenn man die yaml Dateien nimmt und dann die mit dem richtigen Workflow zusammensetzt, dann werden auch die Entitäten/Klassen richtig verwendet.

Und ja, es hat noch gar viele unschönheiten in der Api Spezifikation

hbuerger

@eppjo sagte in Verwendung von Schemas in openapi.json:

Und es werden auch gleich Fehler angezeigt.
Z.B. bool statt boolean, int statt integer, required wo es nicht hingehörte. Evtl falsche Verwendung von oneOf?

Das tut mir leid, ich werde nachher mal gucken, wo das drin steht und es beheben. Solche falschen Typen kommen leider rein, weil wir angefangen haben die OpenAPI per Hand zu schreiben. Dieses Vorgehen ist im Nachhinein doch fehleranfälliger als gedacht. Ich bin gerade dabei die ganze Dokumentation umzustrukturieren, damit wir zukünftig Stoplight Studio verwenden. Damit verspreche ich mir viel.

Zum anderen sind z.T. Datums Felder definiert, obwohl ein date-time zurück geschickt wird, und das noch nicht mal im ISO Format, was wiederum dem unmarshalling nicht schmeckte und mich zum aufgeben brachte

Eigentlich sollten alle unsere Datumsfelder im Zulu Format zurückgegeben werden. Was ja ein date-time Format ist. Wenn es nur das Datum ist, dann sollte natürlich auch date als Format angegeben sein.

@aschild sagte in Verwendung von Schemas in openapi.json:

@eppjo Ja, die openapi.json ist von den Entitäten her nicht brauchbar, das es für jeden Request/Parameterversion eigene Entitäten erstellt.
Wenn man die yaml Dateien nimmt und dann die mit dem richtigen Workflow zusammensetzt, dann werden auch die Entitäten/Klassen richtig verwendet.

Und ja, es hat noch gar viele unschönheiten in der Api Spezifikation

@aschild Kannst du das ausführen? Was meinst du mit "eigene Entitäten"? Wie wäre denn der "richtige" Workflow?
Ich bin ja durch aus bestrebt eine gute Dokumentation zu liefern. Wenn ihr hier Tipps habt was man verbessern kann/sollte nur her damit.

aschild

@hbuerger Schau dir mal die ersten drei Posts in diesem Thread an, die erklären das Problem relativ gut.
Insbesondere der 3. Post eigt was ihr mit den Yaml Dateien machen müsstet damit etwas wiederverwendbares für Codegeneratoren rauskommt.

Ich habe das mit @davidschilling angeschaut und würde mithelfen.
Aber "dank" dem kleinen Ding das unser Leben so verändert hat bin ich bisher nicht dazu gekommen. Aber langsam habe ich wieder etwas mehr Kapazität und kann dann dort weiterfahren.

eppjo

@hbuerger sagte in Verwendung von Schemas in openapi.json:

Eigentlich sollten alle unsere Datumsfelder im Zulu Format zurückgegeben werden. Was ja ein date-time Format ist. Wenn es nur das Datum ist, dann sollte natürlich auch date als Format angegeben sein.

Hier ein Beispiel mit dem falschen Datumsformat beim Abrufen eines Events.
Definiert ist:

"requestedDate": {
  "type": "string",
  "format": "date"
},

Als Response kommt aber:

...
"serviceId": 7,
"agreed": true,
"isValid": true,
"requestedDate": "2020-04-28 12:35:56",
"requesterPersonId": 301,
"requesterPerson": {
  ...

hbuerger

Das ist eindeutig falsch. Danke. Ich pass es an, dass hier date-time und das Zulu Format verwendet wird.

PS: Ich finde es super, wenn ihr solche Fehler meldet. Es ist leichter für mich, wenn ihr auch gleich den jeweiligen Endpoint nennt, dann muss ich nicht suchen