Embed Swagger Content for HTML5 Help Centers

To use Swagger/Open API content in Paligo, you can either embed it or import it. The best approach for you will depend on your requirements.

  • Embedding is useful if your Swagger/Open API content exists elsewhere on the internet, external to Paligo. By embedding it, you add a "live" version of the content to a Paligo topic. However, there are some limitations with how you can format the content, as it is not in the Paligo database and so cannot be processed by Paligo during publishing.

  • Importing is useful if you need to be able to format the Swagger/Open API content in Paligo. With an import, you bring the Swagger/Open API content into the Paligo database, where you have more control over the formatting, just like regular Paligo content. But you will need to import the content manually each time it is updated.

In this section, we explain how to embed Swagger/Open API content. To find out about importing, see import Swagger content into Paligo

To embed Swagger content in a topic and then publish to Zendesk:

  1. In your HTML5 Help Center layout, enable the Swagger embed option, under "Analytics and other integrations".

  2. Select Layout in the top menu and either create a new HTML5 help center layout or edit an existing HTML5 help center layout.

  3. Edit the layout:

    • Select Analytics and other integrations and then enable the Swagger embed option.

    • Consider where the topic that will contain the embedded Swagger content is going to be positioned in the publication structure (table of contents).

      If the topic is going to be at the second-level or lower, select the General category of settings and then enable the Use a short and flat URL structure for output files option.

      If the topic is going to be at the top-level, do not enable the Use a short and flat URL structure for output files option.

  4. Select Save.

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

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

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

    add-link-element.jpeg

    Add a role attribute to the link, with the value swagger-ui.

  9. 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
  10. Publish the publication, making sure to use the layout where you made the above settings. The output should look something like this:

    swagger-sample-output.png

    You should have a sub navigation menu on the left for each of the endpoints in your Swagger content, and all of the interactivity of the Swagger content should work.

Note

If you get an error saying "No API definition provided", this is not an error on the Paligo side. It usually means that you have a "CORS" (cross-origin resource sharing) issue, which is a security setting on your server.

You can test if this is the issue by bypassing CORS. There are CORS bypass extensions that you can add to your browser for this purpose. Please note that Paligo takes no responsibility for how you test CORS issues. If you are uncertain, please consult your development team.

If your testing shows that CORS is causing a problem, ask your developers to enable CORS on the server where you host your Swagger content.