Portal Manager-Seite im Jitterbit API Manager

Einführung

Die Seite Portal Manager ermöglicht es dir, OpenAPI-Dokumentation für alle benutzerdefinierten und Proxy-APIs in einer Umgebung auf einmal zu generieren. Die resultierende Dokumentation wird auf der Seite API Portal angezeigt, wo du damit interagieren kannst, indem du APIs testest. Um stattdessen Dokumentation für eine einzelne API zu generieren, verwende die Registerkarte Dokumentation auf der Seite APIs. Diese Seite beschreibt die Benutzeroberfläche der Seite Portal Manager im API Manager.

Einschränkungen

Die Seite Portal Manager hat diese Einschränkungen:

• Die Generierung von OpenAPI-Dokumentation für OData-APIs wird bei Verwendung von Docs neu generieren nicht unterstützt. Um Dokumentation für eine einzelne OData-API zu generieren, verwende die Registerkarte Dokumentation auf der Seite APIs.
• Die Generierung von OpenAPI-Dokumentation für API-Services mit einer benutzerdefinierten Anfragemethode wird aufgrund einer Einschränkung der OpenAPI-Spezifikation nicht unterstützt. APIs, die nur benutzerdefinierte Methoden-API-Services enthalten, werden nur mit einem API-Tag-Namen angezeigt.
• Pro Umgebung kann in einer Harmony-Organisation nur eine einzelne Seite API Portal erstellt werden.

Zugriff auf die Portal Manager-Seite

Um auf die Seite Portal Manager zuzugreifen, verwende das Harmony-Portalmenü, um API Manager > Portal Manager auszuwählen.

OpenAPI-Editor

Der OpenAPI-Editor enthält die folgenden Steuerelemente:

• Umgebung: Verwende das Menü, um die Umgebung auszuwählen, in der OpenAPI-Dokumentation generiert und dann auf der Seite API Portal einer Organisation angezeigt wird.

  Hinweis

  Pro Umgebung kann in einer Harmony-Organisation nur eine einzelne Seite API Portal erstellt werden.

• Logo-Upload: Du kannst die Seite API Portal anpassen, indem du ein Bild in die Upload-Zone ziehst und ablegen oder manuell eines auswählst. Dein Upload wird automatisch auf der Seite API Portal veröffentlicht, ohne dass du auf Docs neu generieren oder Speichern und veröffentlichen klicken musst.

• Docs neu generieren: Klicke hier, um OpenAPI 2.0-Dokumentation für alle benutzerdefinierten und Proxy-APIs in der ausgewählten Umgebung neu zu generieren und auf der Seite API Portal zu veröffentlichen. OData-APIs sind ausgeschlossen. Wenn du eine neue benutzerdefinierte oder Proxy-API veröffentlicht hast und die Dokumentation automatisch neu generieren möchtest, um neue APIs einzubeziehen, musst du diese Option verwenden.

  Alle Anpassungen, die du zuvor an der Dokumentation gespeichert hast, werden beibehalten und automatisch wo möglich erneut angewendet. Wenn eine Anpassung mit der neu generierten Dokumentation in Konflikt steht, musst du den Konflikt auflösen, bevor du die Dokumentation speichern und veröffentlichen kannst. Weitere Informationen findest du unter Anpassungskonflikte auflösen.

• Speichern und veröffentlichen: Klicke hier, um die API-Dokumentation zu speichern und auf der Seite API Portal zu veröffentlichen. Wenn du Anpassungen an der automatisch generierten API-Dokumentation vorgenommen hast, musst du diese Option verwenden, um die Dokumentation auf der Seite API Portal zu veröffentlichen. Diese Schaltfläche ist deaktiviert, bis alle Anpassungskonflikte behoben sind.

• Editor: Wenn du OpenAPI-Definitionen im Editor hinzufügst, werden sie als interaktive Swagger UI-Dokumentation in der Portal-Vorschau dargestellt. Du kannst die OpenAPI-Definitionen direkt im Editor bearbeiten. Dies sind Beispiele für Anpassungen an der API-Dokumentation:

• Füllen Sie Metadaten zur API aus, einschließlich Fixed Fields wie title, description, termsOfService, contact, license und version.

• Dokumentation manuell mit der OpenAPI Specification 3.0 überschreiben.

Nach dem Bearbeiten der API-Dokumentation klicken Sie auf Save and Publish, um die Dokumentation auf der Seite API Portal zu speichern und zu veröffentlichen.

Anpassungskonflikte beheben

Wenn Sie auf Regenerate Docs klicken, werden alle zuvor gespeicherten Anpassungen mit der neu generierten OpenAPI-Dokumentation für diese Umgebung verglichen.

• Keine Konflikte: Wenn alle Anpassungen ohne Konflikt erneut angewendet werden können, werden sie automatisch erneut angewendet, und eine Bestätigungsmeldung zeigt an, wie viele Anpassungen erneut angewendet wurden.

• Konflikte: Wenn eine Anpassung mit der neu generierten Dokumentation in Konflikt steht, z. B. wenn sich der zugrunde liegende Wert eines angepassten Feldes geändert hat, wird eine Meldung Customizations detected zusammen mit einer Anzahl ausstehender Anpassungen angezeigt. Regenerate Docs und Save and Publish sind deaktiviert, bis alle Konflikte behoben sind.

  

  Jeder Konflikt wird direkt im Editor zwischen <<<<<<< System generated und >>>>>>> Current customization Markierungen angezeigt, wobei der neu generierte Inhalt über dem Trennzeichen und Ihre vorhandene Anpassung darunter angezeigt wird. Führen Sie für jeden Konflikt einen der folgenden Schritte aus:

  • Anpassung anwenden: Klicken Sie, um Ihre vorhandene Anpassung beizubehalten und den neu generierten Inhalt zu verwerfen.

  • Anpassung ignorieren: Klicken Sie, um Ihre vorhandene Anpassung zu verwerfen und den neu generierten Inhalt beizubehalten.

  • Bearbeiten Sie den Inhalt direkt im Editor, um die in Konflikt stehenden Werte nach Bedarf zu kombinieren oder umzuschreiben.

  Um alle ausstehenden Anpassungen auf einmal zu verwerfen und nur den neu generierten Inhalt beizubehalten, klicken Sie auf Ignore all customizations.

Eine laufende Anzahl von Applied, Ignored und Pending Anpassungen wird über dem Editor angezeigt, während Konflikte vorhanden sind. Nachdem alle Konflikte behoben sind und Pending 0 erreicht, klicken Sie auf Save and Publish, um die behobene Dokumentation auf der Seite API Portal zu veröffentlichen.

Portal Preview

Sie können die API-Definitionen als interaktive Swagger UI Dokumentation in der Portal Preview anzeigen.

• Organization: Die Harmony-Organisation, auf die derzeit zugegriffen wird.

• Search: Geben Sie einen API-Namen, Servicenamen oder eine Methode ein, um die Available APIs nach den Abfrageergebnissen zu filtern.

• Base URL: Die Basis-URL für den API-Service. Klicken Sie auf das Kopiersymbol, um die Basis-URL in die Zwischenablage zu kopieren.

• Available APIs: Gruppiert Ihre API-Services nach der Service-Root, z. B. book oder loan. Klicken Sie auf die Carets , um die APIs in dieser Gruppe zu erweitern oder zu reduzieren. Verwenden Sie Expand/Collapse all, um die API-Liste anzuzeigen oder auszublenden.

APIs testen

Wenn Sie einen API-Endpunkt auswählen, wird die interaktive Swagger UI Dokumentation auf der rechten Seite der Seite angezeigt. Sie können die interaktive Swagger verwenden, um die API-Services zu testen.

• Authorize: Wenn eine der APIs in der ausgewählten Umgebung eine Autorisierung erfordert, die durch ein zugewiesenes Security Profile festgelegt wurde, wird eine Schaltfläche Authorize angezeigt. Wenn Sie auf Authorize klicken, wird ein Dialogfeld mit allen verfügbaren Autorisierungen angezeigt. Füllen Sie die Eingabe nach Bedarf aus, um APIs mit den bereitgestellten Autorisierungsmethoden zu testen.

Das Autorisierungssymbol zeigt an, ob der API-Service eine Autorisierung erfordert:

• : Keine Autorisierung erforderlich.

• : Autorisierung erforderlich.

• Ausprobieren: Klicken Sie, um die API zu testen. Eine konfigurierbare API-Anfrage wird erweitert:

  

  • Abbrechen: Klicken Sie, um die konfigurierbare API-Anfrage zu reduzieren.

  • Ausführen: Nachdem Sie die erforderlichen Anfrageparameter konfiguriert haben, klicken Sie auf diese Schaltfläche, um den Curl und die Anfrage-URL zum Testen zu generieren.

    

  • Curl: Die cURL-Anfrage für die eingegebenen Werte der API-Anfrageparameter. Klicken Sie auf das Kopiersymbol, um den cURL in die Zwischenablage zu kopieren.

  • Anfrage-URL: Die Anfrage-URL für die eingegebenen Werte der Anfrageparameter.

  • Löschen: Klicken Sie, um die eingegebenen Werte der API-Anfrageparameter zu löschen.

Jeder API-Service zeigt mögliche API-Antworten an, die in der API-Dokumentation enthalten sind:

• Serverantwort: Zeigt alle dokumentierten Serverantworten an.

• Antworten: Zeigt dokumentierte HTTP-Statuscodes und deren Beschreibungen an.

Fehlerbehebung

Weitere Informationen zur Fehlerbehebung finden Sie in folgendem Abschnitt im API Manager-Leitfaden zur Fehlerbehebung:

• API Portal spiegelt Projektänderungen nicht wider

• Das Löschen einer API aktualisiert die API Portal-Dokumentation nicht