Articles in this section

Embed Swagger OpenAPI

Avatar
Anders
  • Updated
Follow

To use Swagger Open API content in Paligo, you can either embed it or Import Swagger OpenAPI. 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.

CORS (Cross-origin resource sharing) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. For the Swagger embed to work, the host (where your Swagger content is located) must allow CORS. Either completely, or for the domain where you intend to host your content.

Enable Embed Swagger Content

To be able to embed Swagger OpenAPI in your content, it must first be enabled in your layout.

  1. Select Layout in the top menu.

    Paligo editor. The Layout option in the header menu is highlighted.

    Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.

  2. Select the Layout you want to update or Create a Layout.

    Tip

    You can copy the URL of the Layout Editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the Layout settings.

  3. Select Analytics and other integrations in the sidebar.

    Analytics_and_other_integrations_Layout_small.jpg

  4. Select Enable for Enable embedding Swagger content.

    Enable_embedding_swagger_content.png

  5. Select General in the sidebar.

    Layout_General_HTML5_small.png

  6. Enable or Disable Use a short and flat URL structure for output files depending on where the content will be positioned in the publication structure (table of contents):

    • Enable this option if the content will be at second level or lower.

    • Disable this option if the content will be at top level. Disabled by default.

    Use_a_short_and_flat_URL_structure_for_output_files.jpg

    Note

    Select Disable if the topic will be at top-level. Disabled by default.

  7. Select Save.

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.

Comments

0 comments

Article is closed for comments.

Powered by Zendesk