FAQ

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

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

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. 

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

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.

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.

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.

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

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

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.

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

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:

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.

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.

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}'

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.