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