Designing and developing APIs involve a good amount of repeating and re-writing descriptions. A developer, organization or an independent team would have a multitude of such repeatable components used across various API designs, and constantly rewriting them can be tedious and frustrating. This is where SwaggerHub Domains can help. Simply put, Domains are a collection of reusable components.
The components that can be stored inside a Domain are:
- Definitions : These are models which describe your APIs inputs and outputs
- Path Items: A set of predefined operations that can be reused across paths
- Parameters: Any input into an API
- Responses: The output from making an API call
Domains on SwaggerHub are managed the same way as APIs. 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 across all the APIs which reference the Domain, thus allowing for faster API development and collaboration.
Creating and using a Domain
Every Domain has an owner, a name and a version.
New Domains can be created by clicking on ‘Add New Domain’ found in the top right corner.
After a suitable name and version for the domain is set, the user can add the required components inside the domain. Once the components are put in, the Domain can be published. Here’s a sample Domain to help you get started.
A published Domain can be reliably referenced by other Domains and APIs.
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.
You can also reference Public or shared Private Domains directly using the syntax below:
Created Domains can be edited, bumped to a different version, pushed to Github or deleted. Domains can be either Public or Private. 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. Users can select ‘Search Domains’ in the search bar to search for some neat public Domains on Swaggerhub, published by other users.