Skip to main content

Import Swagger OpenAPI

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.

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

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

In this section, we explain how to import Swagger Open API content. If you want to find out about embedding it, see Embed Swagger OpenAPI.

When you import OpenAPI content into Paligo, the content exists as topics in Paligo and you can edit them in the same way as any other Paligo topic. You can import the content and publish it as it is, or you can import it and then add other topics to it, depending on your needs. Imported OpenAPI content works especially well with Paligo's HTML API style layout, which provides a navigation panel, a content panel and a sample code panel where you can switch between code samples in different programming languages.

swagger-openapi-published-as-apioutput.jpg

Prepare Swagger OpenAPI for Import

You can import Swagger OpenAPI content as json or yaml files. Before you can import your content to Paligo, the project requires some preparation first.

When the import is complete, the Swagger OpenAPI content appears as topics in the Content Manager. You can use Paligo to edit or add content to the topics if you wish. Note that there is also a publication that contains links to the topics. The publication acts as the table of contents for your OpenAPI content and it is where the structure of the documentation is set. You can create extra topics in Paligo and add them to the content imported from your OpenAPI, as well as integrate it with the rest of your software documentation created in Paligo.

You will probably want to use Paligo's HTML5 API layout for publishing as this layout provides the code sample panel as well as the main content. Learn more about the Publish Content.

Important

If your OpenAPI content has circular references, you will need to import your content in json format. The yaml import feature does not support circular references.

To import json or yaml content into Paligo:

  1. Make a zip file containing the json or yaml file that Paligo will import.

  2. Use the Import Wizard to import your content. Select Swagger OpenAPI as import type.

Tip

If you don't have an OpenAPI project yet, you can use this sample to test the import:  https://paligo.zendesk.com/hc/en-us/articles/360007352034-Download-API-Sample-Content. It is to be imported as a Paligo Export File (PEF).