Domains

A domain is a library of common components – such as parameters, responses and data models – that are used across multiple API definitions. API definitions cannot use domains unless they were created with the same API type and version (e.g., an OpenAPI version 2.0 domain cannot be used with an OpenAPI version 3.0 API definition file). If you have installed Enterprise (on-premise), your software version may not support domains. OpenAPI domains have been supported since v. 1.19.3.

Domain examples

OpenAPI 3.0 Domain Example

OpenAPI 2.0 Domain Example

AsyncAPI Domain Example

Create and manage domains

Like APIs, domains can be public or private, unpublished drafts or published. You can have different versions of a domain, rename it, or transfer the ownership to another user or organization.Public and Private APIsPublishing an APIVersioning

Creating a DomainCreate a Domain

Referring to a DomainRefer to a Domain

Managing DomainsManage Domains

Renaming DomainsRename Domains

Transferring Domain OwnershipTransfer Domain Ownership

Domain syntax

The domain structure is similar to API definitions. Domains can be defined by using the OpenAPI 2.0, OpenAPI 3.0 or AsyncAPI syntax.

Specification Version

When you create a domain, you specify the specification version of the domain, swagger: '2.0', openapi: 3.0.0 or asyncapi: 2.x.x. Use the same specification version as in your APIs – API Hub for Design supports cross-referencing only within the same specification and version.Create a Domain

The specification version defines the domain syntax and the available component types.

Existing domains without a version identifier are assumed to be swagger: '2.0'.

Info section

The info section is optional, but it can be used to give your domain a title, description and developer contact information, as shown in the example below. API Hub for Design displays this information in the interactive documentation and in MY hub.Interactive API Documentation

info:
  title: Components
  description: Common components for Acme REST APIs.
  termsOfService: http://example.com/exampleterms/
  contact:
    name: Core team
    url: http://www.example.com/coreteam
    email: apiteam@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.1

The info section structure is the same as in APIs. See Info Object (OpenAPI) or Info Object (AsyncAPI).

Channels (AsyncAPI only)

For AsyncAPI, the channels object is required, however for domains this must be empty.

channels: {}

Components

The components of APIs are specified at the root level of the domain:

OpenAPI componentsOpenAPI Components
AsyncAPI components

Extensions

Like API definitions, domains can contain extensions – arbitrary keys with the x- prefix. You can use them to add custom metadata to your domains and components. Extension properties can be used almost anywhere in domains, but not directly under the parameters, responses and similar keys.

openapi: 3.0.0

components:
  parameters:
    filter:
      in: query
      name: filter
      x-beta: true  # <-------
      schema:
        type: string
      description: Filter string

How to reference domains

To reference the domain components in an API, use absolute $ref links as follows:

# 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

or if you use API Hub for Design On-Premise:

# 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

See Referring to a Domain for details.Refer to a Domain