CentralStation API Validation

[TimTips]

Hallo 42he Team,

ich habe gerade versucht mit swagger code-gen eine java client library für die central station API zu erstellen. Leider lässt sich die aktuelle API-Spezifikation nicht gegen open api 3 validieren.

Das Problem lässt sich einfach nachstellen indem man die Central Station API-Definition (swagger.json) in den Swagger-Editor lädt (https://editor.swagger.io/).
Beim Validieren gibt es mehrere Fehler, die auch zu fehlerhaften Client-Libraries führen.

Gibt es eurerseits Bestrebungen die API konform zu beschreiben / gestalten, so dass die Generierung eines Clients möglich wird?

Vielen Dank im Voraus für eine Antwort und viele Grüße

Tim

[Axel von Leitner]

Hey Tim, 

bitte entschuldige die Probleme. Wir haben mit den Swagger-Docs noch ein paar offene Themen und würden natürlich auch versuchen die von dir genannten Fehler zu beheben. 

Wann wir alle raus haben will ich dir gerade nicht fest versprechen, weil ich noch keine Einschätzung zum Aufwand der Behebung treffen kann. Mir ist beim Test des Swagger-Editors allerdings eine neue Version aufgefallen: https://editor-next.swagger.io/ 

Dort sehe ich auch Fehler in der console, allerdings kann ich zunächst einmal einen Client generieren. 

Viele Grüße

Axel

[Axel von Leitner]

Hey Tim, 

kurzes Update: Wir haben jetzt gerade ein Update mit Fixes zu den Swagger docs deployed. Mit der Version kann ich auch im alten Swagger-Editor einen Client (Ruby habe ich getestet) generieren. 

Für den verbleibenden Fehler haben wir auch bereits einen Plan, wollen zuvor aber noch ein paar andere Dinge vereinheitlichen in den Docs. Ich hoffe auch den in den kommenden Tagen beheben zu können. 

Kannst du bestätigen, dass du mit der neuen Version erstmal weiter machen kannst? 

Gruß und Danke für die Geduld

Axel

[TimTips]

Hi Axel,

danke für die schnelle Reaktion!

Mit eurer neuen Version bekomme ich (so wie vorher auch) eine Java Client-Bibliothek generiert (sowohl im alten als auch im neuen editor). Diese kompiliert nun auch (das ging vorher u.A. aufgrund der enums nicht).

Allerdings kriege ich beim Aufruf der API nun andere Probleme. In erster Linie scheint das an einem Bug zu liegen, der für Java in diesen issues dokumentiert ist:

https://github.com/swagger-api/swagger-codegen/issues/10196

https://github.com/OpenAPITools/openapi-generator/issues/1095

aber auch für andere Sprachen exisitert. Scheinbar wird unsinniger Code für die "allOf" Schemata Auswahl generiert.Dadurch schlägt zum Beispiel ein Aufruf von "

apiPeopleGet" also GET /api/people bzw. das deserialisieren der JSON Response in ein Java Objekt fehl. "missing discriminator field: <>"

Ich hab gerade leider keine Zeit mich weiter auf die Fehlersuche zu machen.
Wenn ihr in der Angelegenheit noch weitere Schritte macht, würde ich mich freuen, wenn du mir Bescheid sagst. Dann könnten wir eine Synchronisation unserer Daten mit Central Station nochmal in Angriff nehmen.

Viele Grüße

Tim

[Axel von Leitner]

Hey Tim, 

Danke dir für die Hilfe und sorry, dass ich mich jetzt erst melde. Ich hatte vor einigen Monaten bereits die Validation-Fehler in der swagger.json ausgemerzt. Gerade sind nur noch zwei Kleinigkeiten offen gewesen, die mit unserem nächsten Deploy auch weg sein sollten. Du solltest damit dann hoffentlich keine Probleme mehr haben bei der Generierung der Bibliothek. 

Falls doch lass es mich bitte wissen. 

Gruß

Axel