Swagger UI

Die Swagger UI des rc_cube ermöglicht es Entwicklern, die REST-API – beispielsweise zu Entwicklungs- und Testzwecken – leicht darzustellen und zu verwenden. Der Zugriff auf http://<host>/api/ oder auf http://<host>/api/swagger (der erste Link leitet automatisch auf den zweiten Link weiter) öffnet eine Vorschau der allgemeinen API-Struktur des rc_cube, einschließlich aller verfügbaren Ressourcen und Anfragen . Auf dieser vereinfachten Benutzeroberfläche lassen sich alle Funktionen erkunden und austesten.

Bemerkung

Der Benutzer muss bedenken, dass die Swagger UI des rc_cube, auch wenn sie zur Erprobung der REST-API bestimmt ist, eine voll funktionstüchtige Schnittstelle ist. Das bedeutet, dass alle ausgelösten Anfragen tatsächlich bearbeitet werden und den Zustand und/oder das Verhalten des Geräts beeinflussen. Dies gilt insbesondere für Anfragen des Typs PUT, POST und DELETE.

_images/swagger_ui_overview.png

Abb. 41 Startansicht der Swagger UI des rc_cube, bei der die Ressourcen und Anfragen in nodes, templates, datastreams, logs und system gruppiert sind.

Mithilfe dieser Schnittstelle können alle verfügbaren Ressourcen und Anfragen erprobt werden, indem diese durch Klick auf- und zugeklappt werden. Die folgende Abbildung zeigt ein Beispiel dafür, wie sich der aktuelle Zustand eines Moduls abrufen lässt, indem die Schaltfläche Try it out! betätigt, der erforderliche Parameter (node-Name) ausgefüllt und anschließend Execute geklickt wird. Daraufhin zeigt die Swagger UI unter anderem den curl-Befehl an, der bei Auslösung der Anfrage ausgeführt wurde, sowie den Antworttext, in dem der aktuelle Status des angefragten Moduls in einer Zeichenfolge im JSON-Format enthalten ist.

_images/swagger_ui_example_simple_get.png

Abb. 42 Ergebnis nach Abfrage des Status des rc_stereomatching-Moduls

Einige Aktionen, wie das Setzen von Parametern oder der Aufruf von Services, bedürfen komplexerer Parameter als eine HTTP-Anfrage. Die Swagger UI erlaubt es Entwicklern, die für diese Aktionen benötigten Attribute, wie im nächsten Beispiel gezeigt, während der Laufzeit zu erkunden. In der folgenden Abbildung werden die Attribute, die für den set_pose-Service des rc_hand_eye_calibration-Moduls benötigt werden, erkundet, indem eine GET-Anfrage zu dieser Ressource durchgeführt wird. Die Antwort enthält eine vollständige Beschreibung des angebotenen Services, einschließlich aller erforderlichen Argumente mit ihren Namen und Typen in einer Zeichenfolge im JSON-Format.

_images/swagger_ui_example_get_service_args.png

Abb. 43 Ergebnis der GET-Anfrage zum set_pose-Service zeigt die für diesen Service benötigten Argumente

Der Benutzer kann diesen vorformatierten JSON-Text als Muster für die Argumente nutzen, um damit den Service tatsächlich aufzurufen:

_images/swagger_ui_example_fill_service_args.png

Abb. 44 Ausfüllen der Argumente des set_pose-Services