Verwendung von Schemas in openapi.json



  • 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:
    771ebe8e-7246-4bce-a056-9f27335ba3c3-grafik.png
    Hier ist die saubere Lösung beschrieben, mittels $ref: die Verknüpfung zu den definierten Datentypen machen.

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



  • @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...



  • 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 😉



  • @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 Habs gerade selber rausgefunden: /api


  • ChurchToolsMitarbeiter

    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)



  • @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...


  • ChurchToolsMitarbeiter

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



  • @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 😉


  • ChurchToolsMitarbeiter

    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.


Log in to reply