FAQ

Last modified on February 26, 2021

Here are answers to frequently-asked-questions about SwaggerHub. Don’t see what you’re looking for? Visit our Community forum.

What is SwaggerHub for?

SwaggerHub is an integrated API Development platform, built for teams, that brings the core capabilities of the Swagger framework to design, build, document and deploy APIs. SwaggerHub enables development teams to collaborate and coordinate the entire lifecycle of an API with the flexibility to integrate with the toolset of your choice.

Is SwaggerHub free?

APIs make the world a better place for developers, and SwaggerHub has been designed to allow users to take advantage of a lot of its functionality, for free. There are premium features which do cost money, and those can be purchased with a monthly or yearly subscription. You can always downgrade to free if you want.

To create APIs, you’ll need to create a SwaggerHub account.

But I use GitHub / Bitbucket / GitLab, how is this different?

Source control is great for source. But API definitions are not quite the same - they deserve their own, first-class treatment. SwaggerHub works in conjunction with version control systems, so hunting through source code should no longer be necessary.

SwaggerHub does allow connections to GitHub, GitLab, Bitbucket, Azure DevOps Services, and Azure DevOps Server. See here to learn more about our integrations.

My APIs need to be private. What can I do?

Private APIs are available to organizations on paid plans. There are different plans based on the number of APIs and collaborators you’ll need. You can always start a free trial to try our various features. Visit the Pricing page for details on plans and trials.

I want to upgrade my plan. What are the payment options available?

We accept payment via Discover, MasterCard, and Visa. For every transaction, you will receive an email receipt from SwaggerHub to your registered email address.

Using SwaggerHub

What browsers can I use with SwaggerHub?

SwaggerHub and SwaggerHub On-Premise work in the latest versions of:

  • Google Chrome
  • Mozilla Firefox
  • Apple Safari (on macOS only)
  • Microsoft Edge

Other browsers and older versions might work, but they are not officially supported or tested.

What does Publishing an API do?

When you create an API and make it available for users to consume, you are creating a contract for them. They rely on that definition to work a certain way, and breaking changes will potentially break their integrations.

Publishing an API is specific to a single version of an API. You should do so when the API ships and users can rely on the signatures. It tells your teams and consumers that your API is in a stable state. Once published, it is read-only and cannot be changed.

When published, you should consider making changes in a new version of your API.

After you publish, you may want to update the defaul version of the API. This is what is shown in search results, or when someone navigates to your API directly without a specific version number. You can Learn more about versioning.

Of course, there are always unforeseen situations where you may have a typo or need to make an emergency change. You can Unpublish your API but please do so carefully. Trust with your users is precious!

Learn more about publishing APIs.

Does SwaggerHub support versioning?

Yes, you can version APIs, and deprecate old, outdated API contracts. You can learn more about versioning here.

What is the difference between Name and Title of an API?

The Name field of the API is used to uniquely identify the API in SwaggerHub. Consider this part of a permalink to the API definition. It is also used for programmatic access to your definition through the SwaggerHub CLI, SwaggerHub Registry API, and other tools.

Collaboration

I need to share my definitions with other users. How is this done?

Both public and private definitions can be shared with others easily. These users are called Collaborators in the system, and can have read-only or read-write access to an API.

Learn more about collaboration.

Is there a limit to the number of collaborators I can add to my API?

Yes, the number of collaborators is limited, and is based on the tier you’re in. Visit the Pricing page for details on the number of collaborators.

How can I use SwaggerHub with my Company?

SwaggerHub supports the concept of organizations. Each organization can have teams which will let you add users to logical groups. An API can be given permissions to individuals or in bulk to teams.

Learn more about organizations.

I need to access my definitions programmatically. How do I do it? What if they’re private?

You can always reach public APIs from the public SwaggerHub API:

https://api.swaggerhub.com

In simple terms, your API definitions can be accessed through this pattern:

https://api.swaggerhub.com/apis/{owner}/{api}/{version}

You can always navigate all your APIs by going here:

https://api.swaggerhub.com/apis/{owner}

This returns a response in the apis.json format.

For protected APIs that you have access to, you can get an API key from SwaggerHub and use it to access protected API definitions. To retrieve an API key, go to Settings > API Keys. You can then generate an API key which can be used as a header when accessing your data. For example:

curl -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.59

Will return a JSON version of this definition. If you want YAML, tell it with the Accept header:

curl -H Accept:application/yaml -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.59
The API key has access to your data, so keep it safe!

I generated a client SDK. Now what?

This depends on the language that you’re working with. In general, the client SDK is not useful on its own- you’ll want to use a program to call it directly. Each language and framework has different options for usage. Check out the README.md in the output files - it should help get you started.

Integrations

What are integrations?

Integrations are free add-ons to your API definition on SwaggerHub to improve and expand its functionality. These Integrations help connect your API to a host of third-party tools which allow you to go beyond just API design on SwaggerHub! You could sync your definition with a GitHub repository, quickly generate a mock for your OpenAPI definition or create a webhook to trigger for certain events on SwaggerHub!

Learn more about integrations.

Can I add multiple Integrations to the same API?

Yes, you can add multiple Integrations to the same API. The Integrations could be different, for example, an API can have a GitHub Sync and a Webhook integration enabled. An API can also have the same integrations enabled twice. For example, two different Amazon API Gateway integrations can be added to the same API to sync the API with two separate Gateway instances.

Does API Auto Mocking allow for adding business logic?

No, in its current state, the mock generated by API Auto Mocking cannot send specific responses based on input.

Domains

What are Domains?

Any API designer knows that API development involves a lot of reusing and rewriting definitions and descriptions. Domains are a collection of such reusable components, which can then be referenced from other APIs and Domains. Some examples of components that can be stored inside a Domain are:

  • Definitions
  • Path Items
  • Parameters
  • Responses

Users can create and version Domains, and then define the components inside them. The components can be referenced from other APIs or Domains, either by the user or the collaborators on the API. Domains can also act as a control center for multiple APIs. One change in a Domain can quickly transmit the change across all the APIs which reference the Domain, thus allowing for faster API development and collaboration.

Learn more about Domains.

Who can view my Domains?

Domains can have two visibility levels: private and public. As the names suggest, public Domains can be searched for, viewed, referenced and forked by other SwaggerHub users, while private Domains can only be viewed and worked on by you and the collaborators you’ve added.

Can I reference other Domains from my Domain?

You can reference your own Domains, public Domains, or private Domains shared with you by other users. Currently, Domains require absolute references to other Domains. Just follow the syntax below to reference one Domain from another.

# OpenAPI 3.0
$ref: 'https://api.swaggerhub.com/domains/{owner}/{domainName}/{version}#/components/{componentType}/{componentName}'

# OpenAPI 2.0
$ref: 'https://api.swaggerhub.com/domains/{owner}/{domainName}/{version}#/{componentType}/{componentName}'

How can I search for other Domains?

Public Domains can be searched, viewed, referenced and forked by other users of SwaggerHub. Users can use the Type: Domain filter in the search bar to search for some neat public Domains on SwaggerHub, published by other users.

See Also

SwaggerHub Documentation

Highlight search results