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 simple monthly subscription. You can always downgrade to free if you want.
To create APIs, you’ll need to create a SwaggerHub account, just click the
Sign Up button in the upper right of the SwaggerHub website.
But I use GitHub / Bitbucket / GitLab, how is this different?
Source control is great for source. But API definitions aren’t 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 the GitHub, GitLab and Bitbucket, with others on the way. See here to learn more about our integrations.
My APIs need to be private. What can I do?
Private APIs are available 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. 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.
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.
Why are there two different UIs for Swagger?
Indeed there are two different user interfaces for working with Swagger definitions. The Editor tab provides a YAML-based text editor with contextual auto-suggestions for content. On the right side of the screen, a live rendering is produced, making it easy to visualize the API definition that you’re creating.
Alternatively the UI tab will show you a read only view of the API, tailored for consumers of the API. We have found that these distinct views give the most flexibility for understanding the intent of the API.
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 default 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 here.
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!
Does SwaggerHub support versioning?
Yes, you can version APIs, and deprecate old, outdated API contracts. You can learn more about versioning APIs here.
What is the difference between Name and Title of an API?
Name field of the API is used to uniquely identify the API in SwaggerHub. Once set, it cannot be changed. Consider this part of a permalink to the API definition, it is also used for programmatic access to your definition through the SwaggerHub Public API.
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.
How can I use SwaggerHub with my Company?
SwaggerHub supports the notion 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.
I need to access my definitions externally. How do I do it? What if they’re private?
You can always reach public APIs from the public SwaggerHub API. The API access itself is defined here:
In simple terms, your API can be accessed through this pattern:
You can always navigate all your APIs by going here:
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 the settings. 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.10
Will return a JSON version of this definition. If you want YAML, tell it with the
curl -H Accept:application/yaml -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.10
Note that this token has access to your data, so keep it safe!
I downloaded the 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. Please see the
README.md in the output files–it should help get you started.
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 3rd 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 Swagger definition or create a webhook to trigger for certain events on SwaggerHub!
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 the Auto-Mocking Integration allow for adding business logic?
No, in its current state, the mock generated by the VirtServer Integration cannot send specific responses based on input.
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. The components that can be stored inside a Domain are-
- Path Items
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.
Who can view my Domains?
Domains are of two types- 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. We offer two free Public Domains to all our users. Check out our plans to know more.
Can I reference other Domains from my Domain?
You can reference your own Domains, Domains which are Public 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.
How can I search for other Domains?
Public domains can be searched, viewed, referenced and forked by other users of SwaggerHub. Users can select ‘Search Domains’ in the search bar to search for some neat public Domains on SwaggerHub, published by other users.