Skip to main content

Importing OpenAPI Specification

In this section, you will learn how to import OpenAPI (Swagger) specification data into Apidog.

Apidog supports importing json or yaml files in OpenAPI 3 and Swagger 2 data formats.

If summary, operationId and path parameters are both written within the same Swagger file, the API's name will be set on the Apidog based on the priority of summary > operationId > path.

Manual Import​

Open the Setting and click on "Import Data" to select either file import or URL import.

Manual Import - File Import​

You can drag and drop the JSON or YAML file into the area shown in the figure below, or click the area to select the corresponding JSON or YAML file from the system's file manager.

importing openapi data

Manual Import - URL Import​

tip

When using URL import, you need to provide the URL of the JSON or YAML data file, not the Base URL of the Swagger UI.

swagger

importing-from-url

Import - Advanced Settings​

Importing OpenAPI/Swagger formats only includes APIs, Schemas, and environments.

adada

  1. API Coverage Mode

    adada

Same URL coverage: When two files have the same URL and method, the new file will overwrite the old file.

Coverage only if the URL and group are the same: When two files have the same URL and method, and they are in the same group, the new file will overwrite the old file.

Do not import if the URL is the same: When two files have the same URL and method, the new file will not be imported.

Keep both when the URL is the same: When two files have the same URL and method, the new file will be imported, and the old file will not be deleted.

  1. Import to group: Support importing files to specific groups.

    adada

Import API test cases: After turning on the switch, all API test cases under the selected API will be selected by default, and corresponding API test cases can also be selected in the import preview.

Tip: When importing files in non-Apidog format and the API document is overwritten, API test cases with the same name will not be imported, while API test cases with different names will be added.

adada

The data model needs to be independently configured for selecting the coverage mode and importing to groups, as shown in the image.

adada

Starting from version 2.2.18, a new function of "Meanwhile sync folder of the API" has been added. When you need to update the API document in Apidog and want to keep the synchronization of directories with the folders in Swagger, you can turn on the switch of "Meanwhile sync folder of the API".

adada

Automatic Import​

Open the settings panel and click on "Import (Auto Sync)" to set up multiple data sources and synchronize them to specific groups at regular intervals.

tip

Only project administrators have the "Import Data" (manual and automatic import) setting permission.

auto sync

Smart Merge​

Most users import OpenAPI (Swagger) data and then add names, mock rules, parameter descriptions, and return examples for the schemas in Apidog. Backend developers design APIs in Swagger, and other team members maintain, debug, and test APIs in Apidog.

To meet the above scenario and avoid the situation where the automatic/manual import completely overwrites all fields in the data source, Apidog added a "Smart Merge" feature in version 2.2.27-alpha.1.

When you are ready to import OpenAPI (Swagger) data, select "Smart Merge" in "Match Same APIs", and the names, mock rules, parameter descriptions, and return examples of the schemas modified in Apidog will be preserved.