Skip to main content

Swagger OpenAPI importieren

Um Swagger Open API-Inhalte in Paligo zu verwenden, können Sie sie entweder einbetten oder Swagger OpenAPI importieren. Welcher Ansatz für Sie am besten geeignet ist, hängt von Ihren Anforderungen ab.

  • Der Import ist vorteilhaft, wenn Sie die Swagger Open API-Inhalte in Paligo formatieren müssen. Mit einem Import fügen Sie die Swagger Open API-Inhalte der Paligo-Datenbank hinzu, wo Sie die Formatierung genauer steuern können, genau wie bei regulären Paligo-Inhalten. Allerdings müssen Sie die Inhalte bei jeder Aktualisierung manuell importieren .

  • Die Einbettung ist vorteilhaft, wenn Ihre Swagger Open API-Inhalte an anderer Stelle im Internet, außerhalb von Paligo, vorhanden sind. Durch das Einbetten fügen Sie eine „Live“-Version der Inhalte zu einem Paligo Topic hinzu. Die Formatierung der Inhalte ist dann jedoch eingeschränkt, da sie sich nicht in der Paligo-Datenbank befinden und daher während der Veröffentlichung nicht von Paligo verarbeitet werden können.

In diesem Abschnitt erklären wir, wie Sie Swagger Open API-Inhalte importieren. Weitere Informationen zu ihrer Einbettung finden Sie unter Swagger OpenAPI einbetten.

Wenn Sie OpenAPI-Inhalte in Paligo importieren, existieren die Inhalte als Topics in Paligo und Sie können sie wie jedes andere Paligo Topic bearbeiten. Sie können die Inhalte importieren und sie dann je nach Bedarf entweder so veröffentlichen, wie sie sind, oder ihnen weitere Topics hinzufügen. Importierte OpenAPI-Inhalte funktionieren besonders gut mit dem HTML-API-Stil-Layout von Paligo, das ein Navigations-Panel, ein Inhalts-Panel und ein Beispielcode-Panel bietet, in dem Sie zwischen Codebeispielen in verschiedenen Programmiersprachen wechseln können.

swagger-openapi-published-as-apioutput.jpg

Swagger OpenAPI für den Import vorbereiten

Sie können Swagger OpenAPI-Inhalte als json- oder yaml-Dateien importieren. Bevor Sie Ihre Inhalte in Paligo importieren können, muss das Projekt vorbereitet werden.

Wenn der Import abgeschlossen ist, erscheinen die Swagger OpenAPI-Inhalte als Topics im Content Manager. Mit Paligo können Sie die Topics auf Wunsch bearbeiten oder inhaltlich ergänzen. Beachten Sie, dass es auch eine Publikation gibt, die Links zu den Topics enthält. Die Publikation fungiert als Inhaltsverzeichnis für Ihre OpenAPI-Inhalte und legt die Struktur der Dokumentation fest. Sie können in Paligo zusätzliche Topics erstellen und zu den aus Ihrer OpenAPI importierten Inhalten hinzufügen sowie diese in die restliche in Paligo erstellte Softwaredokumentation integrieren.

Am besten verwenden Sie für die Veröffentlichung das HTML5-API-Layout von Paligo, da dieses Layout das Codebeispiel-Panel und den Hauptinhalt bereitstellt. Erfahren Sie mehr über den Inhalte veröffentlichen.

Wichtig

Wenn Ihre OpenAPI-Inhalte Überkreuzverweise enthalten, müssen Sie sie im json-Format importieren. Die yaml-Importfunktion unterstützt keine Überkreuzverweise.

So importieren Sie json- oder yaml-Inhalte in Paligo:

  1. Erstellen Sie eine ZIP-Datei, die die von Paligo zu importierende json- oder yaml-Datei enthält.

  2. Importassistenten verwenden Sie können den ,um Ihre Inhalte zu importieren. Wählen Sie Swagger OpenAPI als Importart aus.

Tipp

Wenn Sie noch kein OpenAPI-Projekt haben, können Sie dieses Beispiel verwenden, um den Import zu testen:  https://paligo.zendesk.com/hc/en-us/articles/360007352034-Download-API-Sample-Content. Es soll als Paligo Export File (PEF) importiert werden.