Import OpenAPI/Swagger documentation

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.

Opening the connector window

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

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

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.

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.

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.

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.

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

Providing a document file

Select Manual mode. Click on the Browse.

Select the appropriate document to import, then click Open.

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

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.

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.

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.

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

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

Results

When the import is completed, click the Finish button.