OpenApiExample

With the OpenApiExample component, you can insert example objects from your API definitions into MDX pages in your portal.

When the component is included in an MDX page, the example object is rendered to look like response and request code samples in Reference pages, together with practical buttons to copy the content and expand/collapse nested objects.

To use the component in an MDX page, you must first import it (usually at the top of the page):

Copy
Copied
import { componentName } from '@redocly/developer-portal/ui';

Then, insert the component code block wherever you want it to appear in the page.

To insert an example object, you must provide the following in your component code block:

  • the definitionId of the API document that contains the example
  • the JSON pointer to a specific example object in the API document

Here is an example of the OpenApiExample component inserted into an MDX page (this page).

{
  • "quantity": 1,
  • "shipDate": "2018-10-19T16:46:45Z",
  • "status": "placed",
  • "complete": false
}

The following code block inserts the OpenApiExample component into the page.

Copy
Copied
<OpenApiExample definitionId="petstore" pointer="#/components/examples/Order" />

Component properties

Use the following properties to customize the component when inserting it into an MDX page. Required properties are marked with an asterisk (*).

Note that the component will not be rendered if you don't include the required properties in your code block.

Props

NameTypeDescription
definitionId*stringSpecifies the API definition to use in the component. The value must match one of the definition IDs from the `oasDefinitions` section of the `siteConfig.yaml` file.
optionsobjectUse Reference docs configuration options in this object to customize the appearance and behavior of the component.
pointer*stringJSON pointer to an example object from the specified API definition that will be used in the component. The pointer should be relative to the root of the API definition in the form of a URI (e.g. `#/components/examples/User`).
mimeTypestringSpecifies which MIME type to display for the example (if provided in the API definition). Default value: application/json

Usage examples

Add the options object

Use the options object to customize the component by applying supported Reference docs options.

The OpenApiExample component supports the following options:

  • jsonSampleExpandLevel

In this example, we're adding some of the supported configuration options to the options object.

Copy
Copied
<OpenApiExample
  definitionId="petstore"
  pointer="#/components/examples/Order"
  options={{
    jsonExpansionLevel: 5,
  }}
/>