Anzeigen von API-Definitionen

Eine API-Definition ist eine technische Beschreibung des Verhaltens einer API. Die API-Definition umfasst in der Regel Folgendes:

  • Die Endpunkte in der API
  • Die von den einzelnen Endpunkten verwendeten Schemen, die bestimmen, wie Nutzdaten strukturiert werden
  • Die von den einzelnen Endpunkten verwendeten Ressourcen
  • Die in den einzelnen Ressourcen verfügbaren Felder
  • Die für jedes Feld geltenden Eigenschaften

Dies sind die gängigen Ansätze zum Anzeigen von API-Definitionen in Cloud-API:

  • Verwenden der Swagger-Benutzeroberfläche
  • Aufrufen des /openapi.json-Endpunkts (oder der /swagger.json) über ein Anforderungstool

Swagger-Benutzeroberfläche

Die Swagger-Benutzeroberfläche (Swagger UI) ist ein Open-Source-Tool, das API-Definitionen als interaktive Webseiten präsentiert. Informationen zur Swagger-Benutzeroberfläche finden Sie auf der Swagger-Website: https://swagger.io/tools/swagger-ui/

Die Swagger-Benutzeroberfläche wird automatisch mit ClaimCenter gebündelt.

Die Swagger-Benutzeroberfläche kann beim Anzeigen von Schemainformationen hilfreich sein. Die Swagger-Benutzeroberfläche stellt diese Informationen hierarchisch dar. Untergeordnete Schemas werden in Bezug auf übergeordnete Schemas eingerückt, und einzelne Knoten der Hierarchie können ausgegeben und reduziert werden. Die Suche in einem komplexen Schema ist in der Swagger-Benutzeroberfläche relativ einfach.

Die Swagger-Benutzeroberfläche entfernt jedoch einige der Metadaten, die in den Quelldateien vorhanden sind. Guidewire-proprietäre Tags werden beispielsweise nicht in der Swagger-Benutzeroberfläche gerendert. Wenn Sie Zugriff auf alle Metadaten für eine API benötigen, ist es möglicherweise besser, den Endpunkt /openapi.json direkt aufzurufen.

Anmerkung: Beachten Sie, dass die Swagger-Benutzeroberfläche auch die Möglichkeit hat, Anforderungen an einen funktionierenden Endpunkt zu senden und die Antworten zu beobachten. Guidewire empfiehlt jedoch, die Swagger-Benutzeroberfläche nur zum Anzeigen von API-Definitionen zu verwenden. Die APIs in der Cloud-API sind deutlich robuster. Beim Senden von Anforderungen über die Swagger-Benutzeroberfläche kann die Leistungszeit zum Abrufen von Antworten unannehmbar lang sein. Weitere Informationen zu den empfohlenen Anforderungstools finden Sie unter Anforderungen und Antworten.

Anzeigen eine rAPI-Definition mit der Swagger-Benutzeroberfläche

Prozedur

  1. Geben Sie den Pfad für die API an. (Eine Liste der Pfade für jede API finden Sie unter Die System-APIs der Basiskonfiguration.)
  2. Starten Sie ClaimCenter.
  3. Geben Sie in einem Webbrowser die URL für die Swagger-Benutzeroberfläche ein. Damit wird das Tool „Swagger UI“ geladen.
    • Das Format der URL ist <applicationURL>/resources/swagger-ui/
    • Für eine lokale Instanz von ClaimCenter verwenden Sie beispielsweise: http://localhost:8080/cc/resources/swagger-ui/
  4. Geben Sie im Textfeld oben in der Benutzeroberfläche von Swagger UI die URL ein, die auf die Datei swagger.json der gewünschten API verweist. Klicken Sie dann auf Explore.
    • Das Format der URL lautet <applicationURL>/rest<APIpath>/swagger.json.
    • Geben Sie zum Anzeigen der Common API beispielsweise Folgendes ein: <applicationURL>/rest/common/v1/swagger.json

Ergebnisse

Der folgende Screenshot zeigt den oberen Bereich der Swagger UI-Anzeige für die Common API.


Benutzeroberfläche von Swagger UI

Organisation von API-Informationen in der Swagger-Benutzeroberfläche

Die Versionsnummer der Cloud-API erscheint oben in einer grauen Blase nach dem API-Namen. (Beachten Sie, dass einzelne APIs keine eindeutigen Versionsnummern haben. Die Versionsnummern, die in der Swagger-Benutzeroberfläche angezeigt werden, gelten für die gesamte Cloud-API-Version.)

Jeder Endpunkt in der API wird in einer Liste angezeigt. Für jede API werden standardmäßig die folgenden Informationen angezeigt:

  • Die Operation des Endpunkts (z. B. GET)
  • Der Pfad des Endpunkts (z. B. /activities)
  • Eine Zusammenfassung des Endpunkts (z. B. „Gibt eine Liste der dem aktuellen Benutzer zugewiesenen Aktivitäten zurück“)

Wenn Sie auf die Operations-Schaltfläche klicken, werden zusätzliche Informationen zum Endpunkt angezeigt. Dazu gehören:

  • Eine detailliertere Endpunktbeschreibung
  • Eine Liste der vom Endpunkt unterstützten Abfrageparameter
  • Eine hierarchische Liste der vom Endpunkt verwendeten Ressourcen und Schemas (Diese wird im Abschnitt Antworten auf der Registerkarte Modell angezeigt.)

Die API-Definitionsendpunkte und Postman

In einigen Situationen ist es hilfreich, die Rohdaten der API-Definition anzuzeigen. In der Cloud-API enthält jede API zwei Endpunkte, welche die API-Definition zurückgeben: /openapi.json und /swagger.json.

  • /openapi.json gibt die API-Definition unter Verwendung der OpenAPI 3.0-Spezifikation zurück, die häufig als „OpenAPI 3.0“ bezeichnet wird
  • /swagger.json gibt die API-Definition unter Verwendung der Swagger 2.0-Spezifikation zurück, die häufig als „Swagger 2.0“ bezeichnet wird
Anmerkung: Die Cloud-API wurde mithilfe der Swagger 2.0-Spezifikation erstellt. Die Definition für jede API kann jedoch entweder in der Swagger 2.0-Spezifikation (mit dem Endpunkt /swagger.json) oder in der OpenAPI 3.0-Spezifikation (mit dem Endpunkt /openapi.json) zurückgegeben werden.

Die API-Definitionsendpunkte können hilfreich sein, wenn Sie alle Metadaten zu einem Endpunkt anzeigen möchten, einschließlich Metadaten, die von der Swagger-Benutzeroberfläche möglicherweise entfernt werden. Die API-Definitionsendpunkte enthalten Informationen jedoch in einem „unformatierten“ Format. Es werden keine Farben, Schriftarten oder Platzierungen verwendet, um Informationen voneinander zu trennen. Schemahierarchien sind nicht so gut lesbar wie in der Swagger-Benutzeroberfläche. Wenn Sie eine Schemahierarchie im Detail überprüfen müssen, ist es möglicherweise einfacher, die Swagger-Benutzeroberfläche zu verwenden.

Aus Sicht der Metadaten ist die OpenAPI 3.0-Spezifikation umfangreicher. Wenn also beide Endpunkt optional verwendet werden können, empfiehlt Guidewire die Verwendung des Endpunkts /openapi.json. Guidewire-proprietäre Tags (wie x-gw-typelist) sind beispielsweise in der Antwort auf /openapi.json aufgeführt, nicht jedoch in der Antwort auf /swagger.json. Einige Tools, die zum Rendern von API-Metadaten verwendet werden, sind jedoch möglicherweise nicht robust genug, um Informationen mit der OpenAPI 3.0-Spezifikation zu verarbeiten. Für solche Situationen ist der /swagger.json-Endpunkt verfügbar.

In der Basiskonfiguration sind die API-Definitionsendpunkte für jeden Aufrufer verfügbar, einschließlich nicht authentifizierter Aufrufer.

Postman

Sie können die API-Definitionsendpunkte mit einem Anforderungstool aufrufen. Anforderungstools werden nicht automatisch mit InsuranceSuite-Anwendungen gebündelt. Sie müssen diese selbst herunterladen und installieren.

Postman ist ein Anforderungstool, das Guidewire empfiehlt. Dieses Tool bietet folgende Möglichkeiten:

• API-Aufrufe speichern, einschließlich Header und Nutzdaten

• Sammlungen von Aufrufen speichern

• Automatisches Erstellen einer Sammlung von Aufrufen für die Pfade eines Schemas durch Importieren der Swagger-Schemadatei

• Gemeinsame Nutzung von Sammlungen mit anderen Entwicklern in Ihrem Team

Weitere Informationen und zum Herunterladen des Tools finden Sie unter https://www.postman.com/.

Anzeigen einer API-Definition mit Postman

Vorbereitungen

Installieren Sie Postman. Weitere Informationen und zum Herunterladen des Tools finden Sie unter https://www.postman.com/.

Warum und wann dieser Vorgang ausgeführt wird

Diese Aufgabe beinhaltet keine Authentifizierungsinformationen. Das liegt daran, dass jeder Aufrufertyp API-Metadaten anfordern kann, einschließlich nicht authentifizierter Aufrufer.

Prozedur

  1. Geben Sie den Pfad für die API an. (Eine Liste der Pfade für jede API finden Sie unter Die System-APIs der Basiskonfiguration.)
  2. Starten Sie ClaimCenter.
  3. Starten Sie Postman.
  4. Starten Sie in Postman eine neue Anforderung, indem Sie auf das + rechts neben der Registerkarte Launchpad klicken.
  5. Stellen Sie sicher, dass unter der Bezeichnung Untitled Request GET ausgewählt ist. (Dies ist die Standardoperation.)
  6. Geben Sie im Feld Enter request URL die folgende URL ein: <applicationURL>/rest<APIpath>/openapi.json (oder <applicationURL>/rest<APIpath>/swagger.json). Geben Sie zum Anzeigen der Common API für eine lokale Instanz von ClaimCenter beispielsweise Folgendes ein:
    • http://localhost:8080/cc/rest/common/v1/openapi.json (OR http://localhost:8080/cc/rest/common/v1/swagger.json)
  7. Klicken Sie rechts vom Anforderungsfeld auf die Schaltfläche Senden.

Ergebnisse

Die API-Informationen werden im Ergebnisbereich angezeigt. Das Folgende ist beispielsweise der erste Teil der Ergebnisse beim Aufrufen des openapi.json-Endpunkts, auf den zuvor verwiesen wurde:

{
    "components": {
        "parameters": {
            "activityId": {
                "description": "The REST identifier for the activity, as returned via previous requests that return a list of activities\n",
                "in": "path",
                "name": "activityId",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
...

Organisation von Informationen in der Ausgabe von API-Definitionsendpunkten

Die Ausgabe der API-Definitionsendpunkte sind JSON-Rohdaten.

  • Allgemeine Informationen zur API finden Sie im Abschnitt info.
  • Die Liste der Endpunkte finden Sie im Abschnitt paths.
    • Wenn ein Endpunktpfad über mehrere Operationen verfügt, wird der Endpunktpfad nur einmal aufgeführt. Jede Operation wird darunter angezeigt.
    • Beispielsweise enthält der Pfad /activities/{activityId} in der Common API Auflistungen für GET und PATCH.
  • Zusammenfassungen und Beschreibungen werden inline zu dem angezeigt, was sie zusammenfassen oder beschreiben.