OpenAPI Components

Component types

OpenAPI domains can contain the following component types:

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

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

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.

See Also

Publication date: