APIs can reference shared components from domains by using the
$ref keyword. Domain references have the following format:
# OpenAPI 2.0 $ref: https://api.swaggerhub.com/domains/OWNER/DOMAIN/VERSION#/TYPE/COMPONENT_NAME # OpenAPI 3.0 $ref: https://api.swaggerhub.com/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME # AsyncAPI 2.x $ref: https://api.swaggerhub.com/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME
|Note:||The SwaggerHub hostname in domain references starts with
In SwaggerHub On-Premise, domain references require
/v1 after the hostname:
# OpenAPI 2.0 $ref: http(s)://SWAGGERHUB/v1/domains/OWNER/DOMAIN/VERSION#/TYPE/COMPONENT_NAME # OpenAPI 3.0 $ref: http(s)://SWAGGERHUB/v1/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME # AsyncAPI 2.x $ref: http(s)://SWAGGERHUB/v1/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME
For example, you would reference the
Order schema from the
common-models domain as follows:
openapi: 3.0.0 paths: /orders: post: summary: Add a new order requestBody: required: true content: application/json: schema: $ref: 'https://api.swaggerhub.com/domains/acme/common-models/1.0#/components/schemas/Order'
The easiest way to insert domain references is to use autocompletion: type
$ref: followed by a space, and then press Ctrl+Space (on Windows) or Option+Space (on Mac). The SwaggerHub editor will display a list of suggestions. Select an item from the list, and SwaggerHub will insert a fully-qualified
In SwaggerHub SaaS, autocompletion displays only local definitions as well as domains of the same owner as the API owner. However, you can also reference any other public or shared private domains by specifying the corresponding
$ref value manually.
In SwaggerHub On-Premise 1.21.0 and later, autocompletion also displays any domains that the current user has access to, including all public domains, domains of all organizations that the user is a member of, and all domains where the user is a collaborator.
APIs can reference only domains with the same specification and version:
AsyncAPI 2.x APIs can reference AsyncAPI 2.x domains.
OpenAPI 2.0 APIs can reference OpenAPI 2.0 domains.
OpenAPI 3.0 APIs can reference OpenAPI 3.0 domains (across any
Domains can reference other domains using the same rules.
Domain references are resolved based on the current user’s access permissions. The user needs at least read access to the referenced domain in order for the reference to be resolved.
Jump to the referenced domain
For OpenAPI domains, you can hover over the domain link in the editor, and then click Jump To. SwaggerHub will open this domain in a new browser tab.
For AsyncAPI domains, you can hold down the Ctrl key (Windows) or the Cmd key (Mac) and click to jump to the domain.