A domain is a library of common components – such as parameters, responses and data models – that are used across multiple API definitions. Domains can be written by using the OpenAPI 2.0 or OpenAPI 3.0 syntax. API definitions can use domains with the matching OpenAPI version.

Note for SwaggerHub On-Premise users: OpenAPI 3.0 domains are supported since v. 1.19.3.

Domain examples

OpenAPI 3.0 Domain Example

OpenAPI 2.0 Domain Example

Component types

Domains can contain the following components:

Definitions (in OpenAPI 2.0) or Schemas (in OpenAPI 3.0) – Data models that describe your API inputs and outputs.
Path items – API paths (such as GET, POST, PUT operations) that can be reused across APIs.
Parameters – Parameters for an API call: path parameters, query string parameters, custom headers, and so on.
Responses – Responses returned by API calls: HTTP status codes and the response data models.

Additional component types in OpenAPI 3.0 domains:

Request bodies – Common request bodies for POST, PUT, and PATCH operations.
Headers – Common response headers (such as rate limit headers) and multipart body part headers.

Note: Common request headers are defined as parameters, not as header components.
Examples – Reusable Example objects for use in parameters, request bodies, and response bodies. These examples can be referenced from the examples keyword (not to be confused with example).
Links – Definitions of the relationship and traversal mechanism between operations. Learn more.
Callbacks –Callback definitions.

Note: The OpenAPI 3.0 components section can contain securitySchemes, however, domains cannot contain them. Domains are for components that are referenced via the $ref keyword, such as $ref: '#/components/schemas/MySchema'. Security schemes, however, are referenced directly by their name:

security:
  - bearerAuth: []  # "bearerAuth" is the name of the security scheme

so they must be defined in the API where they will be used.

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.

Creating a Domain

Referring to a Domain

Managing Domains

Renaming Domains

Transferring Domain Ownership

Domain syntax

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

OpenAPI version

When you create a domain, you specify the OpenAPI Specification version of this domain, swagger: '2.0' or openapi: 3.0.0. Use the same OpenAPI version as in your APIs – SwaggerHub supports cross-referencing only within the same OpenAPI version.

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

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

Components

In OpenAPI 2.0 domains, place your components in the definitions, parameters, responses, and pathitems sections at the root level of the domain. The pathitems syntax is similar to the API paths section, but it uses arbitrary identifiers instead of the actual path names.

definitions:
  ...

parameters:
  ...

responses:
  ...

pathitems:
  EntityOperations:    # An arbitrary name, does not have to be a /path/to/something
    get:
      ...
    post:
      ...

See OpenAPI 2.0 Domain Example.

OpenAPI 3.0 domains need to have everything under the components section. Note that OpenAPI 3.0 uses schemas instead of definitions.

components:
  schemas:
     ...
  pathitems:
     ...
  parameters:
     ...
  requestBodies:
     ...
  responses:
     ...
  headers:
     ...
  examples:
     ...
  links:
     ...
  callbacks:
     ...

See OpenAPI 3.0 Domain Example.

Info section

The info section is optional, but it can be used to give your domain a title, description and developer contact information. SwaggerHub displays this information in the interactive documentation and in MY hub.

info:
  title: Components
  version: 1.0.0
  description: Common components for Acme REST APIs
  contact:
    name: Core team
    email: apiteam@example.com

The info section structure is the same as in APIs. See Info Object.

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

or if you use SwaggerHub 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

See Referring to a Domain for details.

Domains