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/OWNERID/DOMAIN/VERSION#/TYPE/COMPONENT_NAME

# OpenAPI 3.0
$ref: https://api.swaggerhub.com/domains/OWNERID/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME

# AsyncAPI 2.x
$ref: https://api.swaggerhub.com/domains/OWNERID/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME

Note

The API Hub for Design hostname in domain references starts with api, not with app.

In API Hub for Design On-Premise, domain references require /v1 after the hostname:

# OpenAPI 2.0
$ref: http(s)://SWAGGERHUB/v1/domains/OWNERID/DOMAIN/VERSION#/TYPE/COMPONENT_NAME

# OpenAPI 3.0
$ref: http(s)://SWAGGERHUB/v1/domains/OWNERID/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME

# AsyncAPI 2.x
$ref: http(s)://SWAGGERHUB/v1/domains/OWNERID/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 API Hub for Design editor will display a list of suggestions. Select an item from the list, and API Hub for Design will insert a fully-qualified $ref.

Click the image to enlarge it.

In API Hub for Design 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 API Hub for Design 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.Resource Roles

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. API Hub for Design 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.

Refer to a Domain

Note

Autocompletion

Referencing rules

Jump to the referenced domain

See Also

Search results