Refer to a Domain
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 api, not with app.
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'Autocompletion
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 $ref.
 |
Click the image to enlarge it.
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.
Referencing rules
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
openapi: 3.0.xversions)
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.
 |
Click the image to enlarge it.
For AsyncAPI domains, you can hold down the Ctrl key (Windows) or the Cmd key (Mac) and click to jump to the domain.