Importing API Definitions

You can import your existing OpenAPI 3.0, OpenAPI 2.0, or AsyncAPI definitions to API Hub for Design. JSON and YAML definitions can be imported, and valid JSON definitions will be automatically converted to YAML.

The size of the imported file is limited to 10 MB for YAML. When importing a JSON definition, the maximum size of the equivalent YAML definition is 10 MB.

Import an API

  1. In the left sidebar, click the and select Import and Document API.

    API_screenshot_import_api_01.png

  2. The following dialog will appear:

    API_screenshot_import_api_02.png

  3. Fill out the fields:

    • Path or URL – The URL or local path of the API definition to import. For example, http://petstore.swagger.io/v2/swagger.json or C:\Work\petstore.json. To upload a file from your computer, click Browse.

      Note

      See the examples below for tips on importing definitions from Swagger UI, GitHub, and other websites.

    • Owner – Choose whether to create the API in your personal or organization account. The owner ID of the API owner is part of the API path in API Hub for Design: https://app.swaggerhub.com/apis/OwnerID/api-name/1.0. Organization-owned APIs count toward the organization’s limits rather than yours.

      Note

      Organization owners and anyone with the Designer role can create APIs in that organization.

    • Project – If an organization is selected as the Owner, you can optionally select a project to add this API to. The list contains existing projects available to you.Projects

    • Visibility – Choose whether to make the API public or private. Public APIs are visible to anyone, even to people without a API Hub for Design account. Private APIs can be accessed only by owners and by the people added as designers or consumers). You can change the API visibility later if needed.

  4. Click Import.

  5. On the next page, specify the name and version of the imported API:

    API_screenshot_import_api_03.png

    • Name – The API name is its unique ID and is part of its path on API Hub for Design, as in https://app.swaggerhub.com/api/{owner}/petstore/1.0. Requirements:

      • 3 to 60 character long

      • allowed characters: A..Z a..z 0..9 - _ .

      • must start and end with a letter or digit

      Note that API names are case-sensitive, so petstore and PetStore are two different APIs.

      Tip

      To import the definition as a new version of an existing API, enter the name of the existing API.

    • Version – The version of the imported API. It is defined in the info.version field of the definition.

  6. Click Import to complete the import.

After the API is imported, the API Hub for Design editor opens where you can edit the imported API definition.

Import as a version of an existing API

You can use the import feature to import an API definition as a new version of an existing API. To do that, specify the name (ID) of an existing API in the import parameters.

If the API already has the same version number as the one specified in the info.version field of the API file you are importing, this version will be overwritten by the imported definition (unless that version is published – in this case, the import will be rejected).

Tips

Import from Swagger UI

In Swagger UI, the link to the API definition file is usually displayed in the header and below the API title. This is the link you will need to import to API Hub for Design.

Link to OpenAPI definition in Swagger UI

Click the image to enlarge it.

More info: How to export an OpenAPI 2.0 (Swagger) API JSON/YAML file from Swagger UI?

Import from GitHub

Browse to your API definition on GitHub and click Raw to get the link to the actual file. This link looks like https://raw.githubusercontent.com/.... Use this link to import your API definition to API Hub for Design.

If the repository is private, GitHub automatically adds an access token to the link.

Getting a raw link to a file on GitHub

Click the image to enlarge it.

Import from Bitbucket

Browse to your API definition on Bitbucket, and once there, click the ellipsis button (...) and select Open raw. Use the resulting link to import your definition to API Hub for Design.

Getting a raw link to a file on Bitbucket

Note

This approach can only be used to import from public repositories.

Import from GitLab

Browse to your API definition on GitLab and click the Open raw button to get the link to the actual file. Use this link to import your definition to API Hub for Design.

Getting a raw link to a file on GitLab

If the repository is private, you will also need to generate an access token and include it in the link:

  1. If you use GitLab.com, go to https://gitlab.com/profile/personal_access_tokens. If you use self-hosted GitLab, click your user profile picture and select Settings, then select Access Tokens.

  2. Create a token with the read_repository or api scope.

  3. Add ?private_token=YOUR_TOKEN at the end of the raw link:

    https://gitlab.com/MyCompany/MyProject/raw/main/openapi.yaml?private_token=YOUR_TOKEN

Specify the resulting link in the API Hub for Design import dialog.

See Also

In this section:
© 2024
Publication date: