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):
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 |
{- "id": 0,
- "category": {
- "id": 0,
- "name": "string"
}, - "name": "doggie",
- "photoUrls": [
- "string"
], - "tags": [
- {
- "id": 0,
- "name": "string"
}
], - "status": "available"
}
The following code block inserts the OpenApiRequestBody
component into the page.
<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 |
The following code block was used to insert the component without the code samples section.
<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 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 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`). |
hideSamples | boolean | Hides 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.
<OpenApiRequestBody
definitionId="petstore"
pointer="#/components/requestBodies/Pet"
options={{
schemaExpansionLevel: 5,
}}
/>