Skip to main content

Swagger OpenAPI für Zendesk einbetten

Wenn Sie Swagger OpenAPI-Inhalte online haben, können Sie Paligo verwenden, um diese Inhalte in Zendesk darzustellen. Dazu erstellen Sie in Paligo ein Topic und fügen einen Link zu Ihrem Swagger OpenAPI-Inhalt hinzu. Dann veröffentlichen Sie das Topic in Zendesk, wo das Topic als Artikel präsentiert wird. Der Artikel enthält eine eingebettete „Live“-Version Ihres Swagger OpenAPI-Inhalts.

swagger-in-zendesk.jpg

Tipp

Paligo unterstützt die Ausgaben Swagger OpenAPI einbetten und Sie können auch Swagger OpenAPI importieren.

Paligo so einstellen, dass Swagger OpenAPI in Zendesk veröffentlicht wird

Der erste Teil des Prozesses besteht darin, einen Link zu Ihrem Swagger OpenAPI-Inhalt zu einem Topic in Paligo hinzuzufügen und dann in Zendesk zu veröffentlichen. Um in Zendesk zu veröffentlichen, muss Ihre Paligo-Instanz eingerichtet werden, um sich mit Ihrem Zendesk zu verbinden. Weitere Informationen zum Einrichten der Paligo-zu-Zendesk-Verbindung finden Sie unter Paligo mit Zendesk verbinden.

Wenn Ihre Paligo-Instanz für die Verbindung mit Zendesk eingerichtet ist, können Sie den Link zu einem Topic hinzufügen und veröffentlichen:

  1. Topics erstellen die eingebettet werden sollen.

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

    Close up of Element Structure Menu. It shows the section element is selected and the Go to element option is selected.

  3. Wählen Sie Zu Element wechseln aus.

  4. Fügen Sie das Attribut Rolle im Panel „Elementattribute“ mit dem Wert swagger-topic hinzu.

    Element attributes for section element. A role attribute has been added and it has its value set to swagger-topic.

  5. Fügen Sie im Topic ein Element para hinzu (oder verwenden Sie ein vorhandenes leeres Element para.

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

    Element context menu shows a search field and a list of elements that are valid at the current position.

  7. Geben Sie Link ein und wählen Sie ihn aus der Liste aus.

    add-link-element.jpeg

  8. Wählen Sie das Element Link im Menü „Elementstruktur“ aus.

  9. Fügen Sie diese Attribute hinzu in Panel „Elementattribute“

    element-attributes-link.jpg

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

  11. Fügen Sie das Topic einer Publikation hinzu und veröffentlichen Sie es anschließend in einem Zendesk-Layout, siehe In Zendesk veröffentlichen.

    Wenn Sie veröffentlichen, wird der Inhalt in Zendesk „geschoben“ und eine Zip-Datei in Ihren Browser heruntergeladen.

    Sie benötigen die Zip-Datei für den nächsten Teil des Prozesses, nämlich Zendesk so einstellen, dass Swagger OpenAPI-Inhalte von Paligo angezeigt werden .

Zendesk so einstellen, dass Swagger OpenAPI-Inhalte von Paligo angezeigt werden

Wenn Sie Paligo so einstellen, dass Swagger OpenAPI in Zendesk veröffentlicht wird haben, können Sie Zendesk so einrichten, dass der eingebettete Inhalt angezeigt wird:

  1. Melden Sie sich als Administrator bei Ihrem Zendesk an.

  2. Wählen Sie Einstellungen (Zahnradsymbol) und suchen Sie dann in der Kategorie Guide-Einstellungen nach dem Abschnitt Sicherheit. Aktivieren Sie das Kontrollkästchen Unsicheren Inhalt anzeigen.

    unsafe-zendesk.jpg

    Zendesk warnt davor, dass bei Aktivierung dieser Funktion potenziell bösartiger Code beim Anzeigen von Artikeln ausgeführt werden kann. Sie haben die Wahl, aber die Funktion Unsicheren Inhalt anzeigen muss aktiviert sein, damit Javascript funktioniert, und Javascript ist erforderlich, um den Swagger/Open API-Inhalt einzubetten. (Die Funktion muss auch aktiviert sein, wenn Sie nur Videos in Ihren Zendesk-Artikeln zeigen möchten.)

  3. Bestätigen Sie mit Aktualisieren oben auf der Seite.

  4. Wählen Sie Design anpassen (Augensymbol) und dann Ihr Zendesk-Thema, um die Themeneinstellungen anzuzeigen.

  5. Wählen Sie Code bearbeiten aus.

  6. Öffnen Sie den Ordner Assets.

  7. Entpacken Sie die Zip-Datei, die Sie in Ihrem Browser heruntergeladen haben, als Sie von Paligo nach Zendesk veröffentlicht haben (der letzte Schritt in Paligo so einstellen, dass Swagger OpenAPI in Zendesk veröffentlicht wird).

  8. Suchen Sie im heruntergeladenen Paket den Ordner JS > Zendesk und den Ordner CSS > Zendesk. Diese enthalten die CSS- und JavaScript-Dateien, die Sie zu Ihren Zendesk-Assets hinzufügen müssen. Sie können die anderen Dateien im heruntergeladenen Paket ignorieren.

    Paligo output from a Zendesk publication. Files shown in folders, with the js zendesk folder and the css zendesk folder open. In those folders, there are several .js and .css files that you need to copy to your Zendesk's assets.

  9. Fügen Sie die Dateien aus den beiden Zendesk-Ordnern in die Zendesk-Assets-Ordner hinzu oder ziehen Sie sie per Drag-and-Drop.

  10. Öffnen Sie im Zendesk-Thema den Ordner Vorlagen und wählen Sie dann document_head.hbs.

  11. Die Datei document_head.hbs sollte bereits Verweise auf die Asset-Dateien enthalten, die Sie beim ersten Einrichten der Paligo-Zendesk-Verbindung erstellt haben. Sie sollten in etwa so aussehen (der genaue Inhalt hängt davon ab, was Sie sonst noch haben und ob Sie alle von Paligo bereitgestellten Assets verwenden wollen oder nicht):

    <script src="{{asset 'bootstrap.min.js'}}"></script>
<script src="{{asset 'lightbox.min.js'}}"></script>
<script src="{{asset 'paligo-zd-lightbox.js'}}"></script>
<script src="{{asset 'paligo-stickymenu.js'}}"></script>
<script src="{{asset 'paligo-zd-glossary-3.js'}}"></script>
<script src="{{asset 'paligo-zd.js'}}"></script>
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet"/>
<link href="{{asset 'lightbox.min.css'}}" rel="stylesheet"/>
<link href="{{asset 'paligo-zd.css'}}" rel="stylesheet" type="text/css" />
<link href="{{asset 'paligo-stickymenu.css'}}" rel="stylesheet" type="text/css" />

    Anmerkung

    Die Verweise verwenden die Zendesk-Syntax für geschweifte Klammern, um auf hochgeladene Assets zu verweisen.

    Wenn Ihr document_head.hbs diese Verweise nicht enthält, fügen Sie sie hinzu.

    Sie sollten auch den folgenden Code hinzufügen, der für den Swagger-Inhalt bestimmt ist:

    <link id="swaggercss" rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui.css" /> 

<script src="https://cdnjs.cloudflare.com/ajax/libs/js-yaml/3.13.1/js-yaml.min.js"></script> 
<script src="{{asset 'paligo-swagger.js'}}"></script>

  12. Wählen Sie Veröffentlichen aus.

    Ihr Zendesk ist jetzt so eingestellt, dass Swagger-Inhalte angezeigt werden. In Paligo können Sie das Topic mit dem Swagger-Link veröffentlichen und die Ausgabe auf Zendesk setzen. Das Topic wird einem Artikel in Zendesk zugeordnet, und dieser Artikel zeigt den Swagger/Open API-Inhalt, der das „Ziel“ des Links ist.