OpenApiRequestBody

With the OpenApiRequestBody component, you can add request body 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 request schema in Reference pages.

The component displays an expandable schema and optional request code 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 request body 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 request body object in the API document

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

Request Body schema:

Pet object that needs to be added to the store

id
integer <int64>
object (Category)
name
required
string
photoUrls
required
Array of strings
Array of objects (Tag)
status
string

pet status in the store

Enum: "available" "pending" "sold"
{
  • "id": 0,
  • "category": {
    },
  • "name": "doggie",
  • "photoUrls": [
    ],
  • "tags": [
    ],
  • "status": "available"
}

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

Copy
Copied
<OpenApiRequestBody
  definitionId="petstore"
  pointer="#/components/requestBodies/Pet"
/>

For comparison, this is what the OpenApiRequestBody component looks like when code samples are hidden.

Request Body schema:

Pet object that needs to be added to the store

id
integer <int64>
object (Category)
name
required
string
photoUrls
required
Array of strings
Array of objects (Tag)
status
string

pet status in the store

Enum: "available" "pending" "sold"

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

Copy
Copied
<OpenApiRequestBody
  definitionId="petstore"
  pointer="#/components/requestBodies/Pet"
  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 OpenApiRequestBody 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
<OpenApiRequestBody
  definitionId="petstore"
  pointer="#/components/requestBodies/Pet"
  options={{
    schemaExpansionLevel: 5,
  }}
/>