ExplainStep
With the ExplainStep
component, you can add dynamic content that depends on one or more OpenApiTryIt
responses.
The component displays the provided placeholder.
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.
Here is an example of the OpenApiTryIt
with ExplainStep
component inserted into an MDX page (this page).
We should take data.user.id from the body of the response and use it as a userId query parameter in the next requests.
The following code block inserts the OpenApiTryIt
component into the page followed by the ExplainStep
.
<OpenApiTryIt
id="step-1"
definitionId="petstore"
operationId="updatePetWithForm"
/>
<ExplainStep
needs={['step-1']}
placeholder={(step1) => {
if(!step1) {
return (
<Alert variant="danger">
We should take <strong><i>data.user.id</i></strong> from the body of the response
and use it as a <strong><i>userId</i></strong> query parameter in the next requests.
</Alert>
)
} else {
return (
<Alert variant="success">
<strong>User Id: {step1.response.body.data.user.id}</strong>
</Alert>
)
}
}}
/>
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 |
---|---|---|
needs* | array | Supply an array of id's from the predecessor try it requests. Use in combination with `placeholder`. |
placeholder* | string | A function that returns a React component that is displayed until the needs are met. Use in combination with `needs`. |
id | string | Provide an identifier that will act as an `id` attribute of the wrapping element. |
Usage examples
Multiple needs required
We're using the id
property within the OpenApiTryIt
component to identify which steps are required for the needs
to be fulfilled by the explain step.
<OpenApiTryIt
id="step-1"
definitionId="petstore"
operationId="addPet"
defaultExample="Cat"
/>
<OpenApiTryIt
id="step-2"
definitionId="petstore"
operationId="updatePetWithForm"
defaultExample="Cat"
/>
<ExplainStep
needs={['step-1', 'step-2']}
placeholder={(step1, step2) => {
if (!step1) {
return (
<Alert variant="danger">
Add a pet first.
</Alert>
)
} else if (!step2) {
return (
<Alert variant="danger">
Update the pet second.
</Alert>
)
} else {
return (
<Alert variant="success">
<strong>User Id: {step1.response.body.data.user.id}</strong><br />
<strong>Updated at: {step1.response.body.data.user.updated_at}</strong>
</Alert>
)
}
}}
/>