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:
paths:/users/{userId}:get:summary:Get a user by IDparameters:...responses:'200':description:A single user.content:application/json:schema:type:objectproperties:id:type:integername:type:string/users:get:summary:Get all usersresponses:'200':description:A list of users.content:application/json:schema:type:arrayitems:type:objectproperties:id:type:integername:type:string
After:
paths:/users/{userId}:get:summary:Get a user by IDparameters:...responses:'200':description:A single user.content:application/json:schema:$ref:'#/components/schemas/User'/users:get:summary:Get all usersresponses:'200':description:A list of users.content:application/json:schema:type:arrayitems:$ref:'#/components/schemas/User'components:schemas:User:type:objectproperties:id:type:integername: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.
components:# Reusable schemas (data models)schemas:...# Reusable path, query, header and cookie parametersparameters:...# Security scheme definitions (see Authentication)securitySchemes:...# Reusable request bodiesrequestBodies:...# Reusable responses, such as 401 Unauthorized or 400 Bad Requestresponses:...# Reusable response headersheaders:...# Reusable examplesexamples:...# Reusable linkslinks:...# Reusable callbackscallbacks:...
Each subsection contains one or more named components (definitions):
The component names can consist of the following characters only:
A..Z a..z 0..9 . _ -
Examples of valid names:
UserNew_Userorg.example.User401-Unauthorized
The component names are used to reference the components via $ref from other parts of the API specification:
$ref:'#/components/<type>/<name>'
For example:
$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.
components:#-------------------------------# Reusable schemas (data models)#-------------------------------schemas:User:# Can be referenced as '#/components/schemas/User'type:objectproperties:id:type:integerformat:int64name:type:stringError:# Can be referenced as '#/components/schemas/Error'type:objectproperties:code:type:integermessage:type:string#-------------------------------# Reusable operation parameters#-------------------------------parameters:offsetParam:# Can be referenced via '#/components/parameters/offsetParam'name:offsetin:querydescription:Number of items to skip before returning the results.required:falseschema:type:integerformat:int32minimum:0default:0limitParam:# Can be referenced as '#/components/parameters/limitParam'name:limitin:querydescription:Maximum number of items to return.required:falseschema:type:integerformat:int32minimum:1maximum:100default:20#-------------------------------# Reusable responses#-------------------------------responses:404NotFound:# Can be referenced as '#/components/responses/404NotFound'description:The specified resource was not found.ImageResponse:# Can be referenced as '#/components/responses/ImageResponse'description:An image.content:image/*:schema:type:stringformat:binaryGenericError:# Can be referenced as '#/components/responses/GenericError'description:An error occurred.content:application/json:schema:$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:
components:schemas:Pet:$ref:'../models/pet.yaml'# Can now use use '#/components/schemas/Pet' insteadUser:$ref:'https://api.example.com/v2/openapi.yaml#/components/schemas/User'# Can now use '#/components/schemas/User' insteadresponses:GenericError:$ref:'../template-api.yaml#/components/responses/GenericError'# Can now use '#/components/responses/GenericError' instead
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: schemAs vs securitySchemEs). The references are changed accordingly to reflect the new structure: