Import OpenAPI/Swagger documentation

Hubert Książek - Dataedo Team Hubert Książek 3rd June, 2024

Requirements

A document containing the OpenAPI/Swagger specification for the API is required. The document can be in JSON or YAML format. Dataedo supports the 2.0.X and 3.0.X versions of the specification. The document can be provided using: a link, a file on disk, or by pasting.

Sample Swagger document

Opening the connector window

To import OpenAPI/Swagger Specification, click the Add button in the upper left corner and choose New connection.

New connection button

From the sources, choose OpenAPI/Swagger, and then click Next >

Selecting OpenAPI/Swagger connector.

Selecting HTTP methods to import

Use the Methods field to select which HTTP methods (operations) you want to import. By default, all methods are selected.

HTTP methods to import selection

Selecting connector mode

Using the Mode field you can choose how you want to provide the OpenAPI document.

  • URL - specifying the URL to the OpenAPI document.
  • Manual - specifying the location of the file on disk with the OpenAPI document.
  • if you want to paste the content of the OpenAPI document, you can do it in both modes.

Selecting the mode of import

Providing a document

There are 3 ways to provide an OpenAPI document.

Pasting the document

In the URL and Manual modes, you can directly paste an OpenAPI document. You need to hover over the text field, click the left mouse button, then paste the document (the menu expands when you press the right mouse button on the field), and then click the Connect button.

Pasting the OpenAPI document

Providing a document URL

Select URL mode. You need to hover over the URL text field, click the left mouse button, then paste the URL (the menu expands when you press the right mouse button on the URL text field), and then click the Load button.

Providing a document URL.

Once the document loads in the text box, just click on the Connect button.

Connecting

Providing a document file

Select Manual mode. Click on the Browse.

Browse button

Select the appropriate document to import, then click Open.

Selecting a file

Once the document loads in the text box, just click on the Connect button.

Connecting

Warnings and Errors

When the Connect button is clicked, either Warning or Error may appear.

Warning with a blue checkmark will appear when there are minor inaccuracies, e.g. the property will be of type boolean, and as a default is a string, e.g. "some_text". This will not affect the import, and the message is mainly informative that the document contains errors. In this situation, the only option will be to click OK.

Warning with a blue checkmark.

Error with a yellow checkmark will appear when the error is more serious, for example, the document will not contain the information required by the standard. In such a situation it is still possible to continue the import by clicking Yes, but this may result in the malfunctioning of the program. It is recommended in this situation to verify the document and correct the errors according to the described errors. Clicking No will return to the previous window.

Error with a yellow checkmark.

An Error with a red checkmark will appear when the import is not possible, e.g. when the document is in an unsupported version. In such a situation the only option will be to click OK.

Error with a red checkmark.

Filtering and documentation title

The imported objects will be of type Table. Apart from the previously mentioned option to filter by HTTP methods, there is no option to filter by endpoints. You should click Next >.

Objects to import window

Provide the documentation title and then click on the Import button.

Setting the documentation title

Results

When the import is completed, click the Finnish button.

Imoport.

Result of import

Found issue with this article? Comment below
Comments are only visible when the visitor has consented to statistics cookies. To see and add comments please accept statistics cookies.
0
There are no comments. Click here to write the first comment.