Reusing Descriptions

As is often the case, the example built through the previous pages has grown too large to be easily manageable. This page introduces a mechanism to remove redundancy from an OpenAPI Description (OAD) by reusing portions of it.

The Components Object

The Components Object, accessible through the components field in the root OpenAPI Object, contains definitions for objects to be reused in other parts of the description.

The OpenAPI Object is explained in the Structure of an OpenAPI Description page.
The Schema Object is explained in the Content of Message Bodies page.
The Response Object is explained in the API Endpoints page.
The Parameter Object is explained in the Parameters and Payload of an Operation page.

Most objects in an OAD can be replaced by a reference to a component, drastically reducing the OAD’s size and maintenance cost (just like methods do in programming languages).

Not all objects can be referenced, though, only those listed as fields of the Components Object like schemas, responses and parameters to name a few.

Each field in the Components Object is a map pairing component names with objects to be reused. The type of these objects must match the parent field, e.g. objects in the schemas map must be Schema Objects.

components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true

The above example defines two components:

  • coordinate is a schema component, usable wherever a Schema Object is expected.
  • rowParam is a parameter component, usable wherever a Parameter Object is expected.

The next section explains how to reference these components.

The Reference Object

Any OpenAPI object of the types supported by the Components Object can be replaced by a Reference Object pointing to a component.

Reference Objects are actually JSON References: they contain a single field named $ref and its string value is a URI pointing to the referenced object:

  $ref: 'https://gigantic-server.com/schemas/Monster/schema.yaml'

References can be absolute or relative, and they can include a fragment identifier

$ref: './another_file.yaml#rowParam'

To complete the example from the previous section:

components:
  schemas:
    coordinate:
      type: integer
      minimum: 1
      maximum: 3
  parameters:
    rowParam:
      name: row
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
    columnParam:
      name: column
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/coordinate"
paths:
  /board/{row}/{column}:
    parameters:
      - $ref: "#/components/parameters/rowParam"
      - $ref: "#/components/parameters/columnParam"

Note how all references point to different fragments inside the same document (the one being processed).

Note also how the coordinate schema is used twice (in the rowParam and columnParam parameters), and how these two parameters are referenced from the /board/{row}/{column} path.

Tic Tac Toe Example

The complete Tic Tac Toe sample API (not included here for brevity) makes heavy use of components. Note for example how different endpoints return a #/components/schemas/status on success, or a #/components/schemas/errorMessage on error.

Summary

Whenever the same piece of JSON or YAML is repeated in an OAD, it is probably worth converting it into a component and referencing it everywhere else.

Furthermore, Reference Objects allow splitting a description into several documents to keep them organized and their individual size manageable.

This page has shown that:

  • Reusable Components Objects can be defined by using the components field of the root OpenAPI Object.
  • Components can be referenced from any place where an object of the same type is expected using $ref.
  • References are actually URIs so they are very flexible.

The next page explains how to include documentation and examples in an OpenAPI Description.