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
In the left sidebar, click the and select Import and Document API.
The following dialog will appear:
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
orC:\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.
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.
Click Import.
On the next page, specify the name and version of the imported API:
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.
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.
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.
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.
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.
If the repository is private, you will also need to generate an access token and include it in the link:
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.
Create a token with the
read_repository
orapi
scope.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.