Import Swagger/OpenAPI

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.

  • 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 Content for HTML5 Help Centers.

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

You can import OpenAPI content as json or yaml files.

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. Select the options menu ( ... ) on the folder that you want to contain the imported content. If you do not have a suitable folder, create one in the Content Manager.

  2. Select Import content.

    Paligo displays the import content dialog.

  3. Set the import type to Swagger OpenAPI.

    Paligo displays the Swagger OpenAPI options. You may find that the default settings are appropriate for your needs, but you can change them if you have specific requirements.

    import-content-swaggeropenapi.jpg
  4. Use Select file to choose a zip file containing the json or yaml file that Paligo will import.

    Note

    Note that the json or yaml must be zipped, otherwise you cannot select it for the import.

  5. On the General options tab, you can enable or disable:

    • Try to match components with existing components - We recommend that you leave this option checked as it gives a more efficient import. When this setting is enabled, Paligo compares the import content to any existing content and then only imports new or changed content.

    • Import admonitions as separate components - If your import content uses the same admonitions (notes, warnings, etc.) in several places, we recommend that you check this option. When checked, Paligo will create separate components for the admonitions so that they are reused rather than repeated several times. If most of your admonitions are unique, leave this setting unchecked.

    • Ignore warnings on import validation - Leave this unchecked unless you are experiencing problems when trying to import content. Paligo will usually fix minor problems automatically during the import.

  6. Set the Schema max depth level. This number represents the level of schema objects that can be included in the code samples in your documentation.

    For example:

    Schema max depth level = 1. Paligo does not use referenced schema objects for the samples. The name of the referenced schema is included, but its content is not shown.

    Max depth 1:
    {    "company" : {}
    }

    Schema max depth level = 2. Paligo shows the content of the referenced schema object. If that referenced object includes references to other schema objects, only the names of those objects are shown.

    Max depth 2:
    {    "company" : {
            "name" : "Paligo",
            "country : "Sweden,
            "address" : {}
            }
    }

    Schema max depth level = 3. Paligo shows the content of two levels of referenced schema objects. If the second level of referenced schema objects include references to other schema objects, those references are by name only.

    Max depth 3:
    {    "company" : {
            "name" : "Paligo",
            "country : "Sweden,
            "address" : {
                "street" : "Street Name 123",
                "postcode" : "1234",        
                },    
            }
    }
  7. Set the Code snippet languages. These are the languages that you want to use for code samples in the published output. They will appear as options at the top of the sample code part of the API documentation, if you publish using the API style layout. When a reader selects an option, the code sample changes so that it provides the code in the selected language. For example, if the reader selects JavaScript, the JavaScript code samples are shown.

    Programming language tabs shown at top of the API layout, above the code samples.
    1. Language buttons at the top of the API documentation (published output).

    2. The code sample.

    To choose which languages are included in your import, select an empty part of the field to display a drop-down menu. Choose the language(s) your content includes, for example, PHP.

    code-snippet-languages-selection.jpg

    If you want to remove a language, select the x icon on the blue button for that language.

  8. On the Custom options tab, you can set the:

    • Title prefix - If you want to add text to the start of all imported topics, enter the text in this field.

    • Folder numbering - When Paligo imports your OpenAPI content, it will use folders to organize the topics. Set folder numbering to enabled if you want the folders to have a number prefix or disabled if you want them to use text only (no numbers).

    • Max folder levels - Choose the number of folders that Paligo can use for organizing the imported OpenAPI content. The default is 1, which means that each group of topics will be in one folder. For example, in the following image, the addPet, deletePet, findPetById, and findPets topics are all in a single folder named "2.Default".

      import-folders-set-to-1.jpg

      If you increase the max folder level to 2, the content would be organized so that each topic is in its own folder, like this:

      import-folders-set-to-3.jpg

      You can increase the number of folder levels to whatever number you need for your content. Paligo will create a new folder for each level as long as there is content at that level in the import.

  9. Select OK to begin the import.

    Paligo imports your OpenAPI content. When the import is complete, the OpenAPI content appears as topics in Paligo's 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.

When your OpenAPI content is ready to release, publish it. 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.