Importing API Definitions

Watch the video
 

You can import your existing OpenAPI 3.0, OpenAPI 2.0, or AsyncAPI definitions to SwaggerHub. 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.

    The Import and Document API menu command

  2. The following dialog will appear:

    Importing an API - Step 1

  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 (if you are a member of an organization on SwaggerHub). The API owner is part of the API path in SwaggerHub: https://app.swaggerhub.com/apis/owner/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.

      Note

      This option was added in v. 1.23.

    • Visibility – Choose whether to make the API public or private. Public APIs are visible to anyone, even to people without a SwaggerHub 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:

    Importing an API - Step 2

    • Name – The API name is its unique ID and is part of its path on SwaggerHub, 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 SwaggerHub 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 SwaggerHub.

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

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

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

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 SwaggerHub import dialog.

See Also

In this section:
© 2024
Publication date: