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):
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.
<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 is not rendered if you don't include the required properties in your code block.
Props
Name | Type | Description |
---|---|---|
definitionId* | string | Specifies 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. |
options | object | Use Reference docs configuration options in this object to customize the appearance and behavior of the component. |
pointer* | string | JSON 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`). |
mimeType | string | Specifies 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.
<OpenApiExample
definitionId="petstore"
pointer="#/components/examples/Order"
options={{
jsonExpansionLevel: 5,
}}
/>