SwaggerHub FAQ

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 API Development Lifecycle product developed by SmartBear Software, the company behind Swagger. It puts the Swagger Definition front-and-center in the development process and provides tooling to make better software. As a Lifecycle tool, SwaggerHub helps you continue to iterate on definitions throughout the life of your API.

Is SwaggerHub Free?

Yes! APIs make the world a better place for developers, and SwaggerHub has been designed to allow users to take advantage of most of its functionality, for free. There are premimum feature which do cost money, though, and those can be purchased with a low cost, simple monthly subscription. You can always downgrade to free if you want.

Public features in SwaggerHub can be accessed anonymously, no SwaggerHub account necessary. To create APIs, you’ll need to create a free SwaggerHub account, just click the Sign Up button in the upper right of the SwaggerHub app.

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 and hunting through source code should no longer be necessary with this first-class API tooling.

SwaggerHub does allow connections to the GitHub SCM with others on the way. See below for pushing API definitions directly to your public or private GitHub repository.

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

Private APIs are available by upgrading to a Premium account. There are different plans based on the number of APIs and collaborators you’ll need. Visit the Pricing page for details of plans, or go to your Settings page to upgrade your plan. Click Billing and select the plan you’re interested in. Our payments are securely processed by BrainTree, a PayPal company.

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

We accept payment via Discover, MasterCard, Venmo, and Visa. For every transaction, you will receive an email reciept 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.

  • Free plans allow up to 25 collaborators on each API.
  • Pro plans allow up to 25 collaborators on each API.
  • Power plans allow up to 25 collaborators on each API.

Using SwaggerHub

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 Interactive API Docs tab will show you a read only view of the API, taylored 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. Once published, it is read-only and cannot be changed.

Once published, you should consider making changes in a new version of your API. See the tips on versioning below.

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. This is done by clicking the + button, choosing Edit API Info, and selecting the appropriate Default version in the bottom of the dialog box.

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!

Note: When you publish or unpublish an API Version, all collaborators on the API will receive an email notification.

When should I version? How?

Assuming you have write access to the API, if an API has been published, there will be a Bump Version button where the Save button usually lives. If the API has not been published, click the down-arrow next to the Save button and choose Bump Version.

I want to store my definitions in GitHub as well

You can enable pushing API definitions by clicking navigating to any of your API defnitions, clicking the + button, then Edit GitHub Push.

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

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.

To add collaborators, load the definition you wish to share. Click the Collaboration button and type the username (for individuals) or team (for teams). Collaborators will need to have an active SwaggerHub account in order to be added to an API.

How can I use SwaggerHub with my Company?

SwaggerHub supports the notion of Organizations. You can create them for free! 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.

To create an organization, sign in to SwaggerHub and click the down-arrow in the upper-right of the screen. Choose Settings and then Organizations on the left side of the screen. You can then create an organization.

To add Teams to an organization, click the Edit button next to the Organization you wish to modify, and create a new Team in the resulting screen.

Note that you cannot add members to a team until they have been added to the organization itself! Also billing for private API repositories is separate for an organization than an individual.

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:

swaggerhub-registry

In simple terms, your API 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 the settings page and click API Key on the left. 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 Accept header:

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!

How do I use SwaggerHub Comments?

SwaggerHub Comments allow all collaborators to discuss ideas and share their thoughts on building APIs or Domains in a team, directly on the SwaggerHub Editor. These comments act as tickets on your APIs and Domains to suggest any changes to the spec or bring new ideas to the attention of all the project stakeholders.

Adding a comment is done with the help of the Comment Bar. Clicking on the + found before very line on the SwaggerHub Editor allows you to add a comment to that specific line. The Comment Bar keeps a record of all the comments made on the API or Domain since its creation, allowing your collaborators to quickly view, reply, resolve or re-open them.

Collaborators can add, reply to, resolve and re-open SwaggerHub Comments on any line of the Swagger spec. Best part is, these comments are updated in real time, so you don’t need to do any page refreshes to see what your team has to say.

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.

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 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!

How do you add an Integration to an API on SwaggerHub?

Integrations can be added and managed from the Manage Integrations option, found in the right of your API specification.

Once here, you can click on the + or - buttons to add a new Integration or remove existing Integrations respectively.

What are the available Integrations on SwaggerHub?

SwaggerHub exposes the following Integrations for consumption:

  • GitHub Sync
  • Amazon API Gateway Integration
  • SmartBear VirtServer
  • BitBucket Sync
  • Webhook

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 GitHub Sync Integrations can be added to the same API to sync the SDKs with two seperate GitHub repositories.

How do I use the GitHub Sync?

The GitHub Sync Integration lets users sync their API specification, or the corresponding client/server SDKs with an existing repository on GitHub. You control the synchronization process, and can configure it to best suit your workflow.

The following fields are needed to create a new GitHub Sync Integration:

  • Name (Required): This is what the specific Integration will be called
  • GitHub Token (Required): The access token from GitHub allowing users to access GitHub repositories
  • Repository (Required): Name of the GitHub repository
  • Branch (Required): Name of the branch in the GitHub repository where the API needs to sync with
  • Generation Target (Required): The type of output target that users want to add to their GitHub repository
  • Output Folder: Folder in the repository where your target will be synced in
  • Paths: This is how the SwaggerHub Integration lets you control the synchronization process
    • Provided Path: These files will be created if they don’t exist. If they do exist, then the sync will not touch the file. Adding a * will indicate everything in the path.
    • Managed Path: These files will be fully managed by the codegen, and anything new will be added to the repository. Adding a * will indicate everything in the path
    • Ignored Path: These paths will be ignored by the GitHub Sync operation

Once you’ve configured the GitHub Sync Integration, every time the API spec is saved, the synchronization with the specified repository automatically occurs.

Check out this short screencast to see how GitHub synchronization works!

How do I use the Webhook Integration?

The Webhook Integration allows users to listen for events on SwaggerHub and push them to the service definition of the user’s choice. The specified events on SwaggerHub will be triggered every time the API is saved.

The following fields are needed to create a new Webhook Integration:

  • Name (Required): This is what the specific Integration will be called
  • Payload URL (Required)::The URL which will listen for events on SwaggerHub
  • Content Type (Required): The type of content that gets sent to the URL from SwaggerHub
  • Lifecycle Event: The type of events on SwaggerHub that the payload URL listens for

How do I use the SmartBear VirtServer Integration?

The SmartBear VirtServer Integration allows users to create and maintain a semi-static mock server for an API defined on SwaggerHub. This allows you to quickly iterate on how the API actually works. This generated mock will have static responses generated for each produces/response-message combination.

If an operation has multiple responses, the mock will cycle through them sequentially; for example, if an operation has 200, 404 and 500 responses, these responses will be returned in sequence for that operation, every time a request is sent from the Swagger UI on the SwaggerHub Editor.

The following fields are need to configure the VirtServer Integration:

  • Name (Required): This is what the specific Integration will be called
  • API Token: Once an arbitrary API token is specified and the Integration is enabled, each request to the mock server will need to have this token in the Authorization header. This is available only for Private APIs on SwaggerHub
  • Default Response Content Type: The default response content type the mock would return if this wasn’t specified in the API specification
  • Update host setting: Allows the Integration to modify your Swagger spec to update the basepath, host or schemes properties to point to the mock automatically

Does the SmartBear VirtServer 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.

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

How do I create and start using a Domain?

Creating a Domain

Domains are created and managed the same way as you would an API on Swaggerhub. Every Domain has an owner, a name and a version. It should be noted that the name of your Domain must be unique, and shouldn’t share the same name with your APIs or Domains. To create a new Domain, just click on ‘Add New Domain’, found under your username in the top right corner.

Once a suitable name and version is set for the Domain, you can start adding the reusable components ( Definitions, Path Items, Parameters, Responses ) to the Domain. Once the Domain is published, the stored components can be referenced reliably by other APIs or Domains!

Referencing Domains

You can reference one or more of your Domains, Public Domains or shared Private Domains from other APIs and Domains!

Referencing your own Domain is easy! Just start the reference and let Swaggerhub help you choose the right Domain and component with its new auto-suggest feature. Start typing the name of your Domain’s object you wish to reference to bring up the auto-suggests.

Here’s how the auto-suggest brings up the most likely object based on what you typed.

To reduce clutter, the auto-suggest feature suggests domains from the same account as the API you’re editing. However, you can always reference Public or shared Private Domains directly using the syntax below:

$ref: 'https://api.swaggerhub.com/domains/{ownerId}/{domainName}/{domainVersion}#/{componentType}/{componentName}'

Here’s a sample Domain to help you get started.

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 add collaborators to my Domain?

Yes you absolutely can! Open the Domain you want to add collaborators to, and click the Collaborators button on the top right corner, under the gear icon.

You can then find users on SwaggerHub you wish to collaborate with, and add them to your Domain with the desired privileges.

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.

$ref: 'https://api.swaggerhub.com/domains/{ownerId}/{domainName}/{domainVersion}#/{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 select ‘Search Domains’ in the search bar to search for some neat public Domains on Swaggerhub, published by other users.

Both Private and Public Domains that are shared with you by other users can be seen by clicking 'Show my Domains’, found in the top right corner.

Are Domains free?

We offer two free Public Domains to all our users. Check out our affordable plans to get more Domains and start using this powerful feature to its full potential!