Apicurio-studio: Unterstützen Sie Referenzen auf Komponentenobjekte in Spezifikationsdokumenten

Anwendungsfall

Der Hauptanwendungsfall, den dies lösen wird, besteht darin, Benutzern die Möglichkeit zu geben, ihre Datentypdefinitionen zu zentralisieren, möglicherweise in einer einzelnen Datei (oder einem Satz von Dateien). Diese Datentypen können dann in mehreren API-Definitionen genutzt werden, indem auf ihren zentralen Speicherort verwiesen wird.

Überlegungen

Um externe Referenzen zu unterstützen, sind eine Reihe von Verbesserungen erforderlich. Hier ist eine Liste in keiner bestimmten Reihenfolge:

• Die Datenmodellbibliothek (derzeit oai-ts-core aber bald apicurio-data-models ) muss erweitert werden, um einen steckbaren Referenzresolver zu unterstützen. Derzeit können diese Bibliotheken nur interne Referenzen auflösen. Stattdessen muss ein Konsument der Bibliothek in der Lage sein, einen benutzerdefinierten Referenzresolver bereitzustellen, damit externe Referenzen erfolgreich aufgelöst werden können.

• Apicurio Studio sollte eine Ressource im Stil "nur Datentyp" mit einem Editor unterstützen, der sich auf das Entwerfen von Datentypen konzentriert. Dies ermöglicht einen spezifischeren Arbeitsablauf zum Erstellen/Verwalten von Datentypen unabhängig von API-Designs.

• Beim Festlegen eines Typs im API-Design-Editor benötigt das Tool eine Möglichkeit, Typen aus externen Ressourcen auszuwählen. Wir müssen uns überlegen, wie wir dem Benutzer diese externen Typen am besten zur Auswahl anzeigen können. Es kann sein, dass wir für API Designs eine Möglichkeit benötigen, andere Ressourcen/Dateien zu "importieren", damit die Benutzeroberfläche die Auswahlmöglichkeiten für den Benutzer eingrenzen und diese sinnvoll anzeigen kann. Denken Sie daran, dass der Editor alle externen Ressourcen abrufen und analysieren muss, um ihre verfügbaren Datentypen in einer Art Auswahl-UI-Steuerelement anzuzeigen.

• Möglicherweise müssen wir entscheiden, ob Ressourcen des in Bearbeitung befindlichen Datentyps als Quelle für externe Referenzen in einem API-Design verwendet werden können. Mit anderen Worten, sollte es möglich sein, in einem API-Design auf "Snapshot"-Datentypen zu verweisen? Oder sollten wir verlangen, dass eine Datentypressource "final" ist, bevor sie als Quelle für externe Referenzen verwendet werden kann. Im ersteren Fall können wir ein API-Design erst "abschließen", wenn auch seine Abhängigkeiten abgeschlossen sind. Hinweis: Dieses gesamte Konzept erfordert, dass wir finalisierende Ressourcen in Apicurio implementieren!

• Wir müssen entscheiden, wie das $ref-Format aussehen soll, wenn wir auf Apicurio-Ressourcen verweisen. Derzeit hat jedes API-Design (oder jede theoretische Datentypressource) eine eindeutige ID, aber es ist eine undurchsichtige ID, die bei der Erstellung generiert wird. Diese ID ist derzeit die einzige eindeutige Möglichkeit, eine Ressource zu Lösungszwecken zu identifizieren. Sobald eine Ressource fertiggestellt ist (wenn wir ein solches Konzept unterstützen), könnten wir der Ressource vielleicht eine benutzerfreundlichere Kennung zuweisen und diese dann in der $ref-URI verwenden. Was auch immer wir tun, es sollte beachtet werden, dass beim Veröffentlichen einer Ressource in einer API-Registry (ein weiteres zukünftiges Feature) alle $-Referenzen im API-Design auf vernünftige Weise von der API-Registry aufgelöst werden müssen.

Hier einige Informationen zu den zulässigen Werten für ein $ref :

Obwohl der Wert von $ref ein URI ist, ist er kein Netzwerk-Locator, sondern nur ein Bezeichner. Das bedeutet, dass das Schema unter diesem URI nicht zugänglich sein muss, aber es kann es sein. Es liegt im Grunde an der Validator-Implementierung, wie externe Schema-URIs behandelt werden, aber man sollte nicht davon ausgehen, dass der Validator Netzwerkressourcen abruft, die in $ref-Werten angegeben sind.

Weitere Informationen zu Referenzen finden Sie in der OpenAPI-Spezifikation und dem JSON Reference RFC .

Wäre es möglich, die Implementierung von Verweisen auf DataTypes aus einer anderen Spezifikation innerhalb von Apicurio zu priorisieren (anstelle von anfänglichen externen Verweisen)?

Der Grund, warum ich dies sage, ist, dass für jede nicht triviale Verwendung von Swagger einige Querverweisfunktionen erforderlich sind. Wir implementieren beispielsweise verschiedene Dienste, die Datentypen (zB Adressen, Personen etc.) teilen und möchten für die Spezifikationen für all diese Apicurio nutzen. Derzeit können wir jedoch keine Querverweise verwenden.

Wäre es möglich, die Implementierung von Verweisen auf DataTypes aus einer anderen Spezifikation innerhalb von Apicurio zu priorisieren (anstelle von anfänglichen externen Verweisen)?

Der Grund, warum ich dies sage, ist, dass für jede nicht triviale Verwendung von Swagger einige Querverweisfunktionen erforderlich sind. Wir implementieren beispielsweise verschiedene Dienste, die Datentypen (zB Adressen, Personen etc.) teilen und möchten für die Spezifikationen für all diese Apicurio nutzen. Derzeit können wir jedoch keine Querverweise verwenden.

Zugegeben, dies würde uns in das Gebiet der Killer-Apps bringen.

@jsenko Es sieht so aus, als hätten wir, sobald wir das Registry-Impl abgeschlossen haben, eine klare Priorität von der Community. :)

Ich würde das gerne sehen, apicurio bei der Arbeit zu verwenden und Referenzen wären für verschiedene Teams unglaublich nützlich.

Mir ist bewusst, dass dies eine Weile gedauert hat, aber externe Referenzen werden ab Beta 2.46, der nächsten Version (wird hoffentlich morgen fertig), offiziell unterstützt. Es gibt eine neue Benutzeroberfläche zum Importieren von Datentypen und Antworten aus anderen Apicurio Studio-Dokumenten in das aktuelle. Darüber hinaus wurde die Validierung aktualisiert, um das Auflösen von externen http/s sowie von Apicurio-internen Referenzen zu unterstützen. Dies sollte ein guter erster Schritt in Richtung einer ausgereiften Unterstützung für dokumentenübergreifende Referenzen sein.