Components in OpenAPI
Components in OpenAPI are reusable bits of OpenAPI description, which can then be referenced. Reusing components allows for smaller file-sizes, reduces conflicts, and improves consistency across the API.
Components can even be shared between multiple documents, allowing for improved reuse between multiple APIs.
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
email:
type: string
format: email
parameters:
userId:
name: uuid
in: path
description: Unique UUIDv4 of the user
required: true
schema:
type: string
format: uuid
responses:
NotFound:
description: User not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
requestBodies:
User:
content:
application/json:
schema:
$ref: "#/components/schemas/User"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWTComponents can be referenced in other parts of the OpenAPI document using the $ref keyword. The $ref keyword is a JSON Pointer to the component, which is a string that starts with #/components/ and then the component type and name. For example, to reference the User schema defined in the
Components Object, you would use the following $ref:
responses:
"200":
description: User found
content:
application/json:
schema:
$ref: "#/components/schemas/User"To put it all together, here is an example of how to reference all the various components in that previous example:
paths:
/users/{userId}:
get:
summary: Get a user by UUID
parameters:
- $ref: "#/components/parameters/userId"
responses:
"200":
description: User found
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"404":
$ref: "#/components/responses/NotFound"
security:
- bearerAuth: []Components Object
The Components Object is a map of reusable components broken down by type.
components:
<componentType>:
<componentName>: <componentDefinition>The component name can be any valid string, but it is recommended to use a
consistent naming convention across the API. A common naming convention is PascalCase or camelCase.
components:
schemas:
Train:
Station:
BookingPayments:Here are the supported component types as of OpenAPI v3.1:
Last updated on