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


Log in to reply