Embed Swagger/Open API Content for Zendesk

If you have swagger/Open API content online, you can use Paligo to present that content in Zendesk. To make this work, you create a topic in Paligo and add a link to your Swagger/Open API content. Then you publish the topic to Zendesk where the topic is presented as an article. The article contains an embedded "live" version of your Swagger/Open API content.

swagger-in-zendesk.jpg

There are two stages to setting up Paligo and Zendesk to include Swagger/Open API content. First, you should Set Paligo to Publish Swagger/Open API to Zendesk, and then Set Zendesk to Show Swagger/Open API Content from Paligo.

The first part of the process is to add a link to your Swagger/Open API content to a topic in Paligo, and then publish it to Zendesk. To publish to Zendesk, your Paligo instance has to be set up to connect to your Zendesk. To find out more about setting up the Paligo-to-Zendesk connection, see Paligo to Zendesk.

When your Paligo instance is set up to connect to Zendesk, you can add the link to a topic and publish it:

  1. Create or edit a topic that will contain the embedded Swagger content.

  2. In the element structure menu, select the top section element and then select Go to element. Then, in the Element attributes section, make sure the section element is selected and add a role attribute with the value: swagger-topic.

    Element attributes for section element. A role attribute has been added and it has its value set to swagger-topic.
  3. In the topic add a para element (or use an existing empty para element).

    Press Alt and Enter (Windows) or Option ⌥ and Enter (Mac) to display the Element context menu. Then search for the element you want to add or select it from the list.

  4. Inside the para element, add a link element.

    add-link-element.jpeg
  5. In the element structure menu, select the link element. Then add these attributes and values in the Element attributes section:

    • role and set its value to swagger-ui

    • xlink:href and set its value to the URL of the JSON or YAML file of your Swagger content.

      Tip

      If you don't have your Swagger content available yet, but want to test the integration, you can just use the standard Swagger "Pet Store" example, using the URL https://petstore.swagger.io/v2/swagger.json.

    element-attributes-link.jpg
  6. Select Save.

  7. Add the topic to a publication and then publish it using a Zendesk layout. If you need instructions on how to do this, see Publish Content to Zendesk.

    When you publish, the content is "pushed" to Zendesk and a zip file is downloaded in your browser. You will need the zip file for the next part of the process, which is setting Zendesk to show Swagger/Open API content.

When you have Set Paligo to Publish Swagger/Open API to Zendesk, you can set up Zendesk to show the embedded content:

  1. Log in to your Zendesk as an administrator.

  2. Select Settings (cog icon) and then in the Guide settings category, look for the Security section. Check the Display unsafe content box.

    unsafe-zendesk.jpg

    Zendesk provides a warning that enabling this feature means potentially malicious code could be run when viewing articles. This is your choice to make, but the Display unsafe content feature has to be enabled for javascript to work, and javascript is needed to embed the Swagger/Open API content. (The feature also has to be enabled even if you just want to show video in your Zendesk articles.)

  3. Select Update at the top of the page to confirm.

  4. Select Customize Design (eye icon) and then select your Zendesk theme to view the theme settings.

  5. Select Edit Code .

  6. Open the Assets folder.

  7. Unzip the zip file that downloaded in your browser when you published from Paligo to Zendesk (the last step in Set Paligo to Publish Swagger/Open API to Zendesk).

  8. Find the JS > Zendesk folder and the CSS > Zendesk folder in the downloaded package. These contain the CSS and javascript files you need to add to your Zendesk assets. You can ignore the other files in the downloaded package.

    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. Add or drag and drop the files from the two Zendesk folders into the Assets in Zendesk.

  10. In the Zendesk theme, open the Templates folder and then select document_head.hbs.

  11. The document_head.hbs should already contain references to the asset files from when you first set up in the Paligo-to-Zendesk connection. They should look something like this (the exact content may depend on what else you have there and if you have chosen to use all provided Paligo assets or not):

    <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" />

    Note

    The references use the Zendesk curly brackets syntax to refer to uploaded assets.

    If your document_head.hbs does not contain these references, add them.

    You should also add the following code, which is for the swagger content:

    <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. Select Publish.

Your Zendesk is now set to show Swagger content.

In Paligo, you can publish the topic with the Swagger link and set the output to Zendesk. The topic is mapped to an article in Zendesk, and that article shows the Swagger/Open API content that is the "target" of the link.