Components Section
Often, multiple API operations have some common parameters or return the same response structure. To avoid code duplication, you can place the common definitions in the global components
section and reference them using $ref
. In the example below, duplicate definitions of a User object are replaced with a single component and references to that component. Before:
1paths:2 /users/{userId}:3 get:4 summary: Get a user by ID5 parameters: ...6 responses:7 "200":8 description: A single user.9 content:10 application/json:11 schema:12 type: object13 properties:14 id:15 type: integer16 name:17 type: string18 /users:19 get:20 summary: Get all users21 responses:22 "200":23 description: A list of users.24 content:25 application/json:26 schema:27 type: array28 items:29 type: object30 properties:31 id:32 type: integer33 name:34 type: string
After:
1paths:2 /users/{userId}:3 get:4 summary: Get a user by ID5 parameters: ...6 responses:7 "200":8 description: A single user.9 content:10 application/json:11 schema:12 $ref: "#/components/schemas/User"13 /users:14 get:15 summary: Get all users16 responses:17 "200":18 description: A list of users.19 content:20 application/json:21 schema:22 type: array23 items:24 $ref: "#/components/schemas/User"25
26components:27 schemas:28 User:29 type: object30 properties:31 id:32 type: integer33 name:34 type: string
Components Structure
components
serve as a container for various reusable definitions – schemas (data models), parameters, responses, examples, and others. The definitions in components
have no direct effect on the API unless you explicitly reference them from somewhere outside the components
. That is, components
are not parameters and responses that apply to all operations; they are just pieces of information to be referenced elsewhere. Under components
, the definitions are grouped by type – schemas
, parameters
and so on. The following example lists the available subsections. All subsections are optional.
1components:2 # Reusable schemas (data models)3 schemas: ...4
5 # Reusable path, query, header and cookie parameters6 parameters: ...7
8 # Security scheme definitions (see Authentication)9 securitySchemes: ...10
11 # Reusable request bodies12 requestBodies: ...13
14 # Reusable responses, such as 401 Unauthorized or 400 Bad Request15 responses: ...16
17 # Reusable response headers18 headers: ...19
20 # Reusable examples21 examples: ...22
23 # Reusable links24 links: ...25
26 # Reusable callbacks27 callbacks: ...
Each subsection contains one or more named components (definitions):
1components:2 schemas:3 User:4 type: object5 ...6 Pet:7 type: object8 ...
The component names can consist of the following characters only:
1A..Z a..z 0..9 . _ -
Examples of valid names:
1User2New_User3org.example.User4401-Unauthorized
The component names are used to reference the components via $ref
from other parts of the API specification:
1$ref: "#/components/<type>/<name>"
For example:
1$ref: "#/components/schemas/User"
An exception are definitions in securitySchemes
which are referenced directly by name (see Authentication).
Components Example
Below is an example of components
that contains reusable data schemas, parameters and responses. Other component types (links, examples, and others) are defined similarly.
1components:2 #-------------------------------3 # Reusable schemas (data models)4 #-------------------------------5 schemas:6 User: # Can be referenced as '#/components/schemas/User'7 type: object8 properties:9 id:10 type: integer11 format: int6412 name:13 type: string14
15 Error: # Can be referenced as '#/components/schemas/Error'16 type: object17 properties:18 code:19 type: integer20 message:21 type: string22
23 #-------------------------------24 # Reusable operation parameters25 #-------------------------------26 parameters:27 offsetParam: # Can be referenced via '#/components/parameters/offsetParam'28 name: offset29 in: query30 description: Number of items to skip before returning the results.31 required: false32 schema:33 type: integer34 format: int3235 minimum: 036 default: 037
38 limitParam: # Can be referenced as '#/components/parameters/limitParam'39 name: limit40 in: query41 description: Maximum number of items to return.42 required: false43 schema:44 type: integer45 format: int3246 minimum: 147 maximum: 10048 default: 2049
50 #-------------------------------51 # Reusable responses52 #-------------------------------53 responses:54 404NotFound: # Can be referenced as '#/components/responses/404NotFound'55 description: The specified resource was not found.56
57 ImageResponse: # Can be referenced as '#/components/responses/ImageResponse'58 description: An image.59 content:60 image/*:61 schema:62 type: string63 format: binary64
65 GenericError: # Can be referenced as '#/components/responses/GenericError'66 description: An error occurred.67 content:68 application/json:69 schema:70 $ref: "#/components/schemas/Error"
Externally Defined Components
Individual definitions in components
can be specified either inline (as in the previous example) or using a $ref
reference to an external definition:
1components:2 schemas:3 Pet:4 $ref: "../models/pet.yaml"5 # Can now use use '#/components/schemas/Pet' instead6 User:7 $ref: "https://api.example.com/v2/openapi.yaml#/components/schemas/User"8 # Can now use '#/components/schemas/User' instead9
10 responses:11 GenericError:12 $ref: "../template-api.yaml#/components/responses/GenericError"13 # Can now use '#/components/responses/GenericError' instead
This way you can define local “aliases” for external definitions that you can use instead of repeating the external file paths in all references. If the location of the referenced file changes, you only need to change it in one place (in components
) instead of in all references.
Differences From OpenAPI 2.0
OpenAPI 2.0 had separate sections for reusable components – definitions
, parameters
, responses
and securityDefinitions
. In OpenAPI 3.0, they all were moved inside components
. Also, definitions
were renamed to schemas
and securityDefinitions
were renamed to securitySchemes
(note the different spelling: schem_A_s
vs securitySchem_E_s
). The references are changed accordingly to reflect the new structure:
1OpenAPI 2.0 OpenAPI 3.02'#/definitions/User' → '#/components/schemas/User'3'#/parameters/offsetParam' → '#/components/parameters/offsetParam'4'#/responses/ErrorResponse' → '#/components/responses/ErrorResponse'
References
Did not find what you were looking for? Ask the community
Found a mistake? Let us know