Referring to a Domain

Last modified on September 23, 2022

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.

Domain autocompletion

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.x versions)

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

Jumping to a domain

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.

See Also

Creating a Domain
SwaggerHub Editor

Highlight search results