As part of SwaggerHub’s ongoing effort to support the latest version of the OpenAPI Specification, OpenAPI 3.0 (OAS 3.0), the team is excited to announce support in one of the platforms key features — domains.
OAS 3.0 allows developers to take frequently used objects, path items, responses and more – and store them in a list to be referenced across your API definition. SwaggerHub Domains take this to the next level, moving that list of reusable assets to a separate file, allowing it to be referenced and used across multiple different definitions.
With the permissions and sharing capabilities in Swaggerhub, a select group of users can define high-level assets that are then referenced across larger teams and design efforts. These re-usable Domains can be versioned, published, and shared for collaborative feedback.
How can Domains help build better APIs?
Often as the scope and scale of development projects grow, the review and validation process for new changes can become the catalyst for a bottleneck in a larger delivery process. Many teams rely on testing, code linters, or peer review to validate and ensure that new services meet organizational style guidelines– but in many cases, these be prone to failure. And, as they are happening after the bulk of development has taken place, the cost of fixing issues is much higher than it would have been earlier in the process.
Domains allow teams to resolve style issues at the design phase before a line of code gets written for a new feature. Validations and changes can happen when there is very little overhead, leading to more confidence in the later stages of development while also keeping the cost of fixing issues to a minimum.
When coupled with our API Standardization feature, teams can create high-level guidelines that are enforced as changes are made, allowing review and validation stages to focus on functionality as opposed to the style and structure of a service. Documentation that is exposed from the same design will share common examples and structure over ones that are being written or generated as part of a build/deployment process.
Domains are available with all plans in SwaggerHub! For more information on configuring and referencing them in definitions, we have several resources in our documentation to get you started.
If you are interested in learning more about how Domains can be paired with our API Standardization feature to enforce guidelines across designs and projects, we recently ran a webinar looking at some of the results from our State of API survey around API design, as well as a demo of the features within SwaggerHub.