Skip to main content

Embed Swagger Content

To publish Swagger content, the topic must first be set as a swagger topic and include a link to the URL of the JSON or YAML file of your Swagger content.

  1. Create a Topic that will contain the embedded Swagger content.

  2. Select the section element in the Element Structure Menu.

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

  3. Select Go to element.

  4. Add the role element in Element Attributes Panel and set the value to swagger-topic.

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

  5. Position the cursor to insert a para element (or use an existing empty para element).

  6. Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.

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

  7. Enter link and select it from the menu.

    add-link-element.jpeg

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

  8. Select the link element in the Element Structure Menu and choose Go to element.

  9. Add the following attributes in Element Attributes Panel.

    • 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 use the standard Swagger "Pet Store" example, using the URL https://petstore.swagger.io/v2/swagger.json.

    element-attributes-link.jpg

  10. Select Save. Save icon.

  11. Publish the publication with the updated layout.

    swagger-sample-output.png

    The output should look something like this: 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" 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. 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.

Please note that Paligo takes no responsibility for how you test CORS issues.

If you experience problems embedding Swagger hosted in Amazon S3, refer to Amazon CORS configuration.