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):

Copy

Copied

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.

Copy

Copied

  <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 will not be 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.

Copy

Copied

<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>
      )
    }
  }}
/>