OpenApiResponse

With the OpenApiResponse component, you can add response schemas from your API definitions to MDX pages in your portal. When the component is included in an MDX page, it is rendered to look exactly like the response schema in Reference pages.

The component displays an expandable schema and optional response samples.

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 a response schema, you must provide the following in your component code block:

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

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

User response

Response Schema: application/json
id
integer <int64>
username
string
firstName
string
lastName
string
email
string
password
string
phone
string
userStatus
integer <int32>

User Status

application/json
{
  • "id": 0,
  • "username": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "password": "string",
  • "phone": "string",
  • "userStatus": 0
}

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

Copy
Copied
<OpenApiResponse
  definitionId="petstore"
  pointer="#/components/responses/UserResponse"
/>

For comparison, this is what the OpenApiResponse component looks like when response samples are hidden.

User response

Response Schema: application/json
id
integer <int64>
username
string
firstName
string
lastName
string
email
string
password
string
phone
string
userStatus
integer <int32>

User Status

The following code block was used to insert the component without the response samples section.

Copy
Copied
<OpenApiResponse
  definitionId="petstore"
  pointer="#/components/responses/UserResponse"
  hideSamples={true}
/>

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 a request body or response 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/requestBodies/UserData`).
hideSamplesbooleanHides the samples section and displays only the schema. Default value: false

Usage examples

Add the options object

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

The OpenApiResponse component supports the following options:

  • jsonSampleExpandLevel
  • schemaExpansionLevel

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

Copy
Copied
<OpenApiResponse
  definitionId="petstore"
  pointer="#/components/responses/UserResponse"
  options={{
    schemaExpansionLevel: 5,
  }}
/>