Last updated

Example Object

The example object is a reusable object and may be defined in components (named examples), separate files, or used directly in Media Type Objects.

Excerpt from the OpenAPI 3.1 specification about the example object

In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

Example Object

Fixed Fields
Field NameTypeDescription
summarystringShort description for the example.
descriptionstringLong description for the example. CommonMark syntax MAY be used for rich text representation.
valueAnyEmbedded literal example. The value field and externalValue field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
externalValuestringA URI that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The value field and externalValue field are mutually exclusive. See the rules for resolving Relative References.

This object MAY be extended with Specification Extensions.

In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

Visuals

The following include visuals of request and response examples.

Response examples

Redocly renders examples in the sample panel. Examples can be provided for the request body and the response body.

responses:
  '200':
    description: Success
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ChessResult"
        examples:
          winning:
            summary: Winning a match
            description: This is a **fictional** win.
            value:
              opponent: hikaru
              result: won
              id: abc123
          losing:
            summary: Losing a match
            description: This is a **fictional** loss.
            value:
              opponent: SenseiDanya
              result: lost
              id: def456

Redocly renders the example in the samples pane. The samples pane is usually on the right panel, but may also be in the main panel in a stacked layout.

examples response

The various examples will be displayed in the select menu. The summary is used as the select menu text. If there is no summary it will fallback to use the named example key (for example, "winning" and "losing" in the example above).

examples response select menu

Request examples

Unlike the response, the request may show the payload or code samples. If the code samples are generated, the examples populate dynamically inside of the code samples.

examples request

The select menu works as it does for the response samples.

Synced examples

If the request examples and response examples have the same mapping key value (in this following example the named example keys are winning and losing).

requestBody:
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/ChessResult"
      examples:
        winning:
          summary: Winning a match
          description: This is a **fictional** win.
          value:
            opponent: hikaru
            result: won
        losing:
          summary: Losing a match
          description: This is a **fictional** loss.
          value:
            opponent: SenseiDanya
            result: lost
responses:
  '200':
    description: Success
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ChessResult"
        examples:
          winning:
            summary: Winning a match
            description: This is a **fictional** win.
            value:
              opponent: hikaru
              result: won
              id: abc123
          losing:
            summary: Losing a match
            description: This is a **fictional** loss.
            value:
              opponent: SenseiDanya
              result: lost
              id: def456

If the mapping key exists Redocly will synchronize the request and response examples when they are changed.

example-switching

Types

const Example: NodeType = {
  properties: {
    value: { isExample: true },
    summary: { type: 'string' },
    description: { type: 'string' },
    externalValue: { type: 'string' },
  },
};