OpenAPI Components
Component types
OpenAPI domains can contain the following component types:
Definitions (in OpenAPI 2.0) or Schemas (in OpenAPI 3.0 and 3.1) – 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 and 3.1 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 applicable in parameters, request bodies, and response bodies. These examples can be referenced from the
exampleskeyword (not to be confused withexample).Links – Definitions of the relationship and traversal mechanism between operations. Learn more.
Callbacks – Callback definitions.
Note: The OpenAPI 3.0 and 3.1 components section can include securitySchemes. However, domains cannot contain such schemes. Domains only include the components 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
For this reason, they must be defined in the API they are used in.
Components
OpenAPI 2.0
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 uses arbitrary identifiers instead of actual path names.
definitions:
...
parameters:
...
responses:
...
pathitems:
EntityOperations: # An arbitrary name, may differ from /path/to/something
get:
...
post:
...OpenAPI 3.0
OpenAPI 3.0 domains must include all their components under the components section. Note that OpenAPI 3.0 uses schemas instead of definitions.
components:
schemas:
...
pathitems:
...
parameters:
...
requestBodies:
...
responses:
...
headers:
...
examples:
...
links:
...
callbacks:
...OpenAPI 3.1
OpenAPI 3.1 domains (similarly to OpenAPI 3.0) must include all their components under the components section. Note that OpenAPI 3.1 uses schemas instead of definitions, and replaces pathitems (from OpenAPI 3.0) with pathItems.
components:
schemas:
...
pathItems:
...
parameters:
...
requestBodies:
...
responses:
...
headers:
...
examples:
...
links:
...
callbacks:
...