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:

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Get a user by ID
5
      parameters: ...
6
      responses:
7
        "200":
8
          description: A single user.
9
          content:
10
            application/json:
11
              schema:
12
                type: object
13
                properties:
14
                  id:
15
                    type: integer
16
                  name:
17
                    type: string
18
  /users:
19
    get:
20
      summary: Get all users
21
      responses:
22
        "200":
23
          description: A list of users.
24
          content:
25
            application/json:
26
              schema:
27
                type: array
28
                items:
29
                  type: object
30
                  properties:
31
                    id:
32
                      type: integer
33
                    name:
34
                      type: string

After:

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Get a user by ID
5
      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 users
16
      responses:
17
        "200":
18
          description: A list of users.
19
          content:
20
            application/json:
21
              schema:
22
                type: array
23
                items:
24
                  $ref: "#/components/schemas/User"
25

26
components:
27
  schemas:
28
    User:
29
      type: object
30
      properties:
31
        id:
32
          type: integer
33
        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.

1
components:
2
  # Reusable schemas (data models)
3
  schemas: ...
4

5
  # Reusable path, query, header and cookie parameters
6
  parameters: ...
7

8
  # Security scheme definitions (see Authentication)
9
  securitySchemes: ...
10

11
  # Reusable request bodies
12
  requestBodies: ...
13

14
  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
15
  responses: ...
16

17
  # Reusable response headers
18
  headers: ...
19

20
  # Reusable examples
21
  examples: ...
22

23
  # Reusable links
24
  links: ...
25

26
  # Reusable callbacks
27
  callbacks: ...

Each subsection contains one or more named components (definitions):

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      ...
6
    Pet:
7
      type: object
8
      ...

The component names can consist of the following characters only:

1
A..Z a..z 0..9 . _ -

Examples of valid names:

1
User
2
New_User
3
org.example.User
4
401-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.

1
components:
2
  #-------------------------------
3
  # Reusable schemas (data models)
4
  #-------------------------------
5
  schemas:
6
    User: # Can be referenced as '#/components/schemas/User'
7
      type: object
8
      properties:
9
        id:
10
          type: integer
11
          format: int64
12
        name:
13
          type: string
14

15
    Error: # Can be referenced as '#/components/schemas/Error'
16
      type: object
17
      properties:
18
        code:
19
          type: integer
20
        message:
21
          type: string
22

23
  #-------------------------------
24
  # Reusable operation parameters
25
  #-------------------------------
26
  parameters:
27
    offsetParam: # Can be referenced via '#/components/parameters/offsetParam'
28
      name: offset
29
      in: query
30
      description: Number of items to skip before returning the results.
31
      required: false
32
      schema:
33
        type: integer
34
        format: int32
35
        minimum: 0
36
        default: 0
37

38
    limitParam: # Can be referenced as '#/components/parameters/limitParam'
39
      name: limit
40
      in: query
41
      description: Maximum number of items to return.
42
      required: false
43
      schema:
44
        type: integer
45
        format: int32
46
        minimum: 1
47
        maximum: 100
48
        default: 20
49

50
  #-------------------------------
51
  # Reusable responses
52
  #-------------------------------
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: string
63
            format: binary
64

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:

1
components:
2
  schemas:
3
    Pet:
4
      $ref: "../models/pet.yaml"
5
      # Can now use use '#/components/schemas/Pet' instead
6
    User:
7
      $ref: "https://api.example.com/v2/openapi.yaml#/components/schemas/User"
8
      # Can now use '#/components/schemas/User' instead
9

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:

1
OpenAPI 2.0                    OpenAPI 3.0
2
'#/definitions/User'         → '#/components/schemas/User'
3
'#/parameters/offsetParam'   → '#/components/parameters/offsetParam'
4
'#/responses/ErrorResponse'  → '#/components/responses/ErrorResponse'

References

Components Object

Did not find what you were looking for? Ask the community
Found a mistake? Let us know