API-Spezifikation als einzelne JSON Datei anbieten

Im Rahmen der Spezifikationsarbeit mit Stoplight wird die Spezifikation aktuell per "$ref" Pointer in wehrfachverwendete Datenmodelle in einzelne JSON Dateien aufgeteilt. (Hintergrund ist u.a. die Wiederverwendung von Modellen über mehrere APIs hinweg)

Um die Weiterverwendung der OpenAPI Spezifikation der FIT-Connect APIs zu verbessern, sollte jede Spezifikationen jeweils zusätzlich in einer konsolidierte JSON Schema Datei angeboten werden. Weiterer Mehrwert hieraus ist auch eine bessere Toolauswahl für die API Dokumentation in FIT-Connect.

Hier sollten zwei Varianten umgesetzt und angeboten werden:

• Bundle mit internen Referenzen (Begründung: Geringere Dateigröße) via swagger-cli bundle
• Dereferenzierte Datei ohne Referenzen (Begründung: Maximal Unterstützung von Tools und Frameworks) via swagger-cli bundle -r

Hierfür wird folgendes Tool vorgeschlagen: https://github.com/APIDevTools/swagger-parser / https://apitools.dev/swagger-parser/ (Gefunden über https://openapi.tools/#parsers)

added 1 deleted label

Die Erzeugung der gebundelten Versionen funktioniert einfach und fehlerfrei.

Installation:

npm install -g swagger-cli

Umwandlung:

swagger-cli bundle -o bundle/sender.json reference/sender.json 
swagger-cli bundle -o bundle/subscriber.json reference/subscriber.json

Die gebundelten Versionen sahen bei einer ersten Prüfung gut aus. Es muss nun geprüft werden, ob sie wirklich kompatibel sind und ob sie Fehler enthalten. Es sollte zusätzlich festgelegt werden, wie sie angeboten werden. Dies könnte z.B. durch ein zweites Repository erreicht werden, welches statt der Verzeichnisse "models" und "reference" nur die Bundles enthält.

Ich würde dem Vorschlag mit dem zweiten Public Repository mitgehen. Eventuell macht es für langfristige Planung Sinn, ein reine Schema Repository vorzusehen, in dem die OpenAPI Spezifikation, aber auch weitere zentrale Schema Modelle öffentlich angeboten werden.

Gibt es schon eine Erfahrung, ob es funktioniert? Eventuell sollte auch die KIV für ihre Implementierung für einen Test des Bundles angefragt werden.

added 1 deleted label and removed 1 deleted label

added 1 deleted label

added workflow::In Progress label

changed the description

Update: Gehen wir im Rahmen der Umstellung auf ReDoc/Rapidoc via GitLab CI an.

marked this issue as related to #42 (closed)

marked this issue as related to #41 (closed)

mentioned in merge request !16 (closed)

Das unterstützten wir nun schon fast. @David_Schwarzmann Kannst Du in RapiDoc einen Download-Button der aktuell dargestellten Spezifikation hinterlegen?

GGf. wäre auch ein Link auf das GitLab-Repo hilfreich.

removed workflow::In Progress label

added workflow::Peer Review label

Die Story ist IMO fertig. Die neuste Version wird immer automatisch auf https://fitko.uber.space/ ausgerollt.

Hab mal das review label drauf.

Ein expliziter Download-Button wäre imho sinnvoll. Dass man die API-Spec über die korrekt zusammengebastelte URL herunterladen kann, ist für Dritte nicht ganz offensichtlich. In Docusaurus sehe ich aktuell keine Möglichkeit, die Spec herunterzuladen.

Ja, aber wir haben hier initial so festgelegt. Wäre für mich erstmal abgeschlossen. Dein Punkt ist valide und sollte heute im Refinement in der FCON-111 ergänzt werden, falls David das noch mitten im Sprint aufnimmt.

removed 1 deleted label

closed