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. Note that OpenAPI 3.1 doesn't support domains.
Create and manage domains
The domain structure is similar to API definitions. Domains can be defined by using the OpenAPI 2.0, OpenAPI 3.0 or AsyncAPI syntax.
When you create a domain, you specify the specification version of the domain,
openapi: 3.0.0 or
asyncapi: 2.x.x. Use the same specification version as in your APIs – SwaggerHub supports cross-referencing only within the same specification and version.
The specification version defines the domain syntax and the available component types.
Existing domains without a version identifier are assumed to be
info section is optional, but it can be used to give your domain a
description and developer contact information, as shown in the example below. SwaggerHub displays this information in the interactive documentation and in MY hub.
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: email@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1
Channels (AsyncAPI only)
For AsyncAPI, the channels object is required, however for domains this must be empty.
The components of APIs are specified at the root level of the domain:
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
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 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 # AsyncAPI 2.x $ref: http(s)://SWAGGERHUB/v1/domains/OWNER/DOMAIN/VERSION#/components/TYPE/COMPONENT_NAME
See Referring to a Domain for details.