Verwendung von Schemas in openapi.json

aschild

Die neue REST API ist cool und bietet viele Vorzüge gegenüber der alten.

Eines ist mir aber aufgefallen:
Es werden zwar diverse Schemas definiert, diese werden dann aber nicht verwendet/referenziert.

zB. gibt es ein Schema "Person" welches definiert ist, dieses wird dann aber weder bei /whoami, /persons/{id} oder den POST/PATCH von /persons verwendet.

Zufälligerweise wird aber eine genau gleiche Datenstruktur an diesen Stellen definiert

Der nun sehr, sehr unschöne Effekt ist, dass man beim generieren eine Clients für jede Datenstruktur eine eigene Klasse erhält, und die via Schema definierte Klasse damit nicht's mehr zu tun hat.

Ein ähnliches Beispiel ist auch die EIgenschaft privacyPolicyAgreement, diese kommt im Schema insgesamt 18x vor, und jedes mal ist wieder die Typendefnition "inline" bei der property definiert. Somit haben wir also 18 Typen für privacyPolicyAgreement, wo doch eine ausreichen würde.

Hier die Klassen die für die 18 "Varianten" generiert werden:

Hier ist die saubere Lösung beschrieben, mittels $ref: die Verknüpfung zu den definierten Datentypen machen.

https://swagger.io/docs/specification/components/

aschild

@aschild
Ich habe noch ein wenig im System gestöbert...

Unter /docs/openApi/openapi.yaml ist die Yaml Beschreibung des Api zu finden, ganz schön sauber mit den Schema Referenzen wie es sein sollte.

Es scheint dass beim anschliessenden generieren des openapi.json die Referenzen verloren gehen und die Schema inline expandiert werden...

aschild

Ich habe nun mal die openapi.yaml genommen und mittels swagger-cli zu einem openapi.json umgewandelt.

Das resultierende json Schema verwendet nun die richtigen Schemadefinitionen, und die .json Datei ist nun 134kB klein, anstelle der 462kB im Original.

https://github.com/APIDevTools/swagger-cli

swagger-cli bundle openapi.yaml -o output2.json

Das wäre die Variante die eine "saubere" openapi 3.0 json Spezifikation erstellt, wenn da diese Variante in euren Buildprozess einbauen könntest

loeti82

@aschild Gibt es vom ChurchTools eine OpenAPI Spezifikation? Wenn ja, über welche URL?

Postman erlaubt es die OpenAPI Spec als Collection zu importieren.
Und vom Swagger client Generator rate ich ab, da dieser sehr träge entwickelt wird. Eine bessere Alternative ist https://github.com/OpenAPITools/openapi-generator als Fork des Swagger generators.

loeti82

@loeti82 Habs gerade selber rausgefunden: <URL zur eigenen Church Tool Seite>/api

hbuerger

Irgendwie ist mir dieser Post durch gerutscht und ich les den erst jetzt

@aschild Du hast recht, beim Konvertieren der YAML Files gehen diese Refs verloren. Danke für den Tip wie es besser laufen kann.

@loeti82 Danke für den Link. Das guck ich mir mal an.

Zudem ich bin gerade am überlegen, ob wir die Specs besser machen können. U.A. bin ich auf Stoplight Studio gestoßen. Hier müsste ich aber an der Struktur wie wir es jetzt machen noch etwas ändern. Aber das sollte euch nicht stören, weil am Schluss immer ein JSON raus kommt (ich hoffe dann aber mit richtigen Refs)

aschild

@hbuerger
Etwas was mich an der Doku stört ist dies:

Das json file deckt ja die Standardfelder/Properties der Objekte ab
Wenn wir nun eigene Felder definieren (Gerade bei Personen + Gruppen) dann fehlen diese in der Doku
Auch wenn man Standardfelder ändern würde, ja, sollte man nicht, aber.... , dann kommt der Standard in der Doku

Wenn man das json File nun zum generieren von Stubs in einer Sprache generieren lässt, dann deckt dieses nur die Standard Felder/Properties und deren Datentypen/Nullvalues etc. ab, aber nicht die Spezialitäten der jeweiligen Installation

Beispiel einer solchen json->PHP Klassenbibliothek Generierung:
https://github.com/vineyardkoeln/churchtools-api/tree/master/src/ChurchTools/Api2

Das hat zwar der Vorteil, dass wir einen generischen CT Client schreiben können, der auf allen Installationen funktioniert.
Aber der Nachteil ist, dass irgendwo noch die Zusatzfelder manuell im Code gepflegt werden müssen.

Ev. wäre es denkbar

eine standard json wie bisher bereitzustellen (Im Buildprozess von CT)
eine an die jeweilige installation angepasste json generieren zu lassen
(Müsste bei der Installation+JedemCTUpdate+JedemFeldAnpassen jeweils auf der Installation neu erstellt werden)

Die andere Variante wäre, via API eine Liste der Zusatzfelder erhalten zu können und die könnte man dann mittels Class Vererbung generieren oder manuell pflegen.

Einfach mal meine Gedanken dazu...

davidschilling

@aschild Die Api für die Zusatzfelder gibt es schon: https://testdavid.church.tools/api/fields

aschild

@davidschilling Ja, aber da ist die ganze Liste der Felder drin, und ich darf manuell schauen was ist Standardlieferumfang und was ist in dieser Installation dazu gekommen.
Ein Flag pro Feld wäre schön

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