Software- und Codedokumentation

3 min read

Swagger OpenAPI einbetten

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.

  • 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.

  • 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 .

CORS (Cross-Origin Resource Sharing) definiert eine Möglichkeit für Client-Webanwendungen, die in der einen Domäne geladen werden, mit Ressourcen in einer anderen Domäne zu interagieren. Damit das Einbetten von Swagger funktioniert, muss der Host (auf dem sich Ihre Swagger-Inhalte befinden) CORS zulassen: entweder vollständig oder für die Domäne, in der Sie Ihre Inhalte hosten möchten.

Einbinden von Swagger-Inhalten aktivieren

Um Swagger OpenAPI in Ihre Inhalte einbetten zu können, muss es zunächst in Ihrem layout aktiviert werden.

  1. Wählen Sie im oberen Menü Layout aus.

    Paligo zeigt eine Liste von Layouts an. Die Liste ist leer, wenn keine benutzerdefinierten Layouts in Ihrer Paligo-Instanz vorhanden sind.

  2. Wählen Sie das Layout, das Sie aktualisieren möchten, oder Ein Layout erstellen aus.

    Tipp

    Sie können die URL des Layout-Editors kopieren und in eine neue Registerkarte in Ihrem Browser einfügen. Dies kann nützlich sein, wenn Sie häufig zwischen Ihren Paligo-Inhalten und den Layout-Einstellungen wechseln.

  3. Wählen Sie in der Seitenleiste Analysen und andere Integrationen aus.

  4. Wählen Sie Aktivieren für Einbinden von Swagger-Inhalten aktivieren aus.

  5. Wählen Sie auf der Seitenleiste Allgemein aus.

  6. Aktivieren oder Deaktivieren Sie Eine kurze und flache URL-Struktur für Ausgabedateien verwenden – je nachdem, wo der Inhalt in der Publikationsstruktur platziert wird (Inhaltsverzeichnis):

    • Aktivieren Sie diese Option, wenn der Inhalt sich auf der zweiten Ebene oder niedriger befinden wird.

    • Deaktivieren Sie diese Option, wenn der Inhalt sich auf der obersten Ebene befindet. Standardmäßig deaktiviert.

    Anmerkung

    Wählen Sie Deaktivieren, wenn das Topic sich auf der obersten Ebene befinden wird. Standardmäßig deaktiviert.

  7. Drücken Sie Speichern.

Swagger-Inhalte einbetten

Um Swagger-Inhalte veröffentlichen zu können, muss das Topic zunächst als Swagger-Topic festgelegt werden und einen Link zur URL der JSON- oder YAML-Datei Ihrer Swagger-Inhalte enthalten,

  1. Topics erstellen die eingebettet werden sollen.

  2. Wählen Sie das section-Element im Menü „Elementstruktur“ aus.

  3. Wählen Sie Zu Element wechseln aus.

  4. Fügen Sie role-Element in Panel „Elementattribute“ hinzu und setzen Sie den Wert auf swagger-topic.

  5. Positionieren Sie den Cursor, um ein para-Element einzufügen (oder verwenden Sie ein vorhandenes leeres para-Element).

  6. Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.

  7. Geben Sie link ein und wählen Sie es im Menü aus.

    Fügen Sie dem link ein role-Attribut mit dem Wert swagger-ui hinzu.

  8. Wählen Sie das link-Element im Menü „Elementstruktur“ aus und wählen Sie Zum Element gehen.

  9. Fügen Sie im Panel „Elementattribute“ die folgenden Attribute hinzu:

    • role, setzen Sie den Wert auf swagger-ui

    • xlink:href und stellen Sie den Wert auf die URL der JSON- bzw. YAML-Datei Ihres Swagger-Inhalts ein.

      Tipp

      Falls Ihr Swagger-Inhalt noch nicht zur Verfügung steht, aber die Integration schon getestet werden soll, können Sie das Standardbeispiel „Pet Store“ von Swagger unter der URL https://petstore.swagger.io/v2/swagger.json verwenden.

  10. Drücken Sie Speichern.

  11. Veröffentlichen Sie die Publikation mit dem aktualisierten Layout.

    Die Ausgabe sollte etwa wie folgt aussehen: Ein Navigations-Untermenü links für jeden der Endpunkte in Ihrem Swagger-Inhalt, und die gesamte Interaktivität des Swagger-Inhalts sollte funktionieren.

Anmerkung

Wenn Ihnen der Fehler „Keine API-Definition vorhanden“ gemeldet wird, handelt es sich nicht um einen Fehler auf Paligo-Seite. Dies bedeutet in der Regel, dass Sie ein „CORS“-Problem haben – das ist eine Sicherheitseinstellung auf Ihrem Server.

Ob dies der Fall ist, können Sie testen, indem Sie CORS umgehen. Hierfür gibt es CORS-Umgehungserweiterungen, die Sie Ihrem Browser hinzufügen können. Bei eventuellen Unklarheiten wenden Sie sich bitte an Ihr Entwicklungsteam.

Sollten Ihre Tests ergeben, dass CORS ein Problem verursacht, bitten Sie Ihre Entwickler, CORS auf dem Server zu aktivieren, auf dem Sie Ihre Swagger-Inhalte hosten.

Bitte beachten Sie, dass Paligo keine Verantwortung dafür übernimmt, wie Sie CORS-Probleme testen.

Sollten Probleme beim Einbetten von Swagger, das in Amazon S3 gehostet wird, auftreten, schauen Sie bitte in die Amazon CORS-Konfiguration.