Components in OpenAPI best practices

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

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

Field

Type

Map[string, Schema Object]*

Description

A map of Schema Objects that can be referenced by other parts of the API. Note: OpenAPI 3.0.x does support OpenAPI Reference Objects as the value here, but

uses the JSON Schema Referencing format.

Type

Map[string, Security Scheme Object | OpenAPI Reference Object]*

Description

A map of Security Scheme Objects that can be referenced by other parts of the API.

Type

Map[string, Path Item Object | OpenAPI Reference Object]*

Description

A map of Path Item Objects that can be referenced by other parts of the API.

Type

Map[string, Parameter Object | OpenAPI Reference Object]*

Description

A map of Parameter Objects that can be referenced by other parts of the API.

Type

Map[string, Request Body Object | OpenAPI Reference Object]*

Description

A map of Request Body Objects that can be referenced by other parts of the API.

Type

Map[string, Response Object | OpenAPI Reference Object]*

Description

A map of Response Objects that can be referenced by other parts of the API.

Type

Map[string, Header Object | OpenAPI Reference Object]*

Description

A map of Header Objects that can be referenced by other parts of the API.

Type

Map[string, Example Object | OpenAPI Reference Object]*

Description

A map of Example Objects that can be referenced by other parts of the API.

Type

Map[string, Callback Object | OpenAPI Reference Object]*

Description

A map of Callback Objects that can be referenced by other parts of the API.

Type

Map[string, Link Object | OpenAPI Reference Object]*

Description

A map of Link Objects that can be referenced by other parts of the API.

Field	Type	Description
	Map[string, Schema Object]*	A map of Schema Objects that can be referenced by other parts of the API. Note: OpenAPI 3.0.x does support OpenAPI Reference Objects as the value here, but uses the JSON Schema Referencing format.
	Map[string, Security Scheme Object | OpenAPI Reference Object]*	A map of Security Scheme Objects that can be referenced by other parts of the API.
	Map[string, Path Item Object | OpenAPI Reference Object]*	A map of Path Item Objects that can be referenced by other parts of the API.
	Map[string, Parameter Object | OpenAPI Reference Object]*	A map of Parameter Objects that can be referenced by other parts of the API.
	Map[string, Request Body Object | OpenAPI Reference Object]*	A map of Request Body Objects that can be referenced by other parts of the API.
	Map[string, Response Object | OpenAPI Reference Object]*	A map of Response Objects that can be referenced by other parts of the API.
	Map[string, Header Object | OpenAPI Reference Object]*	A map of Header Objects that can be referenced by other parts of the API.
	Map[string, Example Object | OpenAPI Reference Object]*	A map of Example Objects that can be referenced by other parts of the API.
	Map[string, Callback Object | OpenAPI Reference Object]*	A map of Callback Objects that can be referenced by other parts of the API.
	Map[string, Link Object | OpenAPI Reference Object]*	A map of Link Objects that can be referenced by other parts of the API.