OpenApiTryIt

With the OpenApiTryIt component, you can add the interactive API console to MDX pages in your portal and let consumers work with your APIs directly from the documentation. When the component is included in an MDX page, it is rendered to look exactly like the Try it console in Reference docs pages.

The component displays request and response tabs with sections for selecting the server, editing the request body, request parameters and security settings.

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 component inserted into an MDX page (this page).

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

<OpenApiTryIt
  definitionId="petstore"
  operationId="updatePetWithForm"
/>

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.

Usage examples

Set the default example

We're using the defaultExample property to specify which example will be displayed by default in the component.

If an example named "Cat" exists for the specified operation, it will be displayed automatically.

<OpenApiTryIt
  definitionId="petstore"
  operationId="addPet"
  defaultExample="Cat"
/>

Set default values for security schemes

With the securityDefaults property, you can specify which values to display by default for security schemes supported by your API definition. This allows you to prefill the credentials fields in the component with values that are safe to use for testing purposes.

In this example, we're setting the default credentials for the OAuth security scheme.

<OpenApiTryIt
  definitionId="petstore"
  operationId="addPet"
  defaultExample="Cat"
  securityDefaults={{
    petstore_auth: {
      client_id: 'TEST_CLIENT_ID',
      client_secret: 'TEST_CLIENT_SECRET',
      token: {
        access_token: 'TEST_ACCESS_TOKEN'
      }
    }
  }}
/>

Work with the response data

With the onResponse property, you can add an optional callback that will be invoked after performing a request in the component. This allows you to perform different actions with the response data.

The onResponse property supports two special arguments: response and request. The request argument can be used to inspect request data received in the component.

In this example, we're redirecting the response and the request data to the console log.

<OpenApiTryIt
  definitionId="petstore"
  operationId="addPet"
  defaultExample="Cat"
  onResponse={({ request, response }) => {
    console.log('request: ', request);
    console.log('response: ', response);
  }}
/>

Add the properties object

Use the properties object to modify one or more values for request body properties. This allows you to show specific values in your examples instead of using the default ones.

By default, the component uses automatically generated example values for request body properties. If you only change the value for one property, the remaining properties will use those automatically generated values.

In this example, we're using the properties object to change the default values for status, id, and tags.name properties in the request body.

<OpenApiTryIt
  definitionId="petstore"
  operationId="addPet"
  defaultExample="Cat"
  properties={{ status: "pending", id: 12, tags: [{"name": "test_subject"}] }}
/>

Add the parameters object

Use the parameters object to add or modify request parameters, and show custom parameter values in your examples instead of the default ones.

You can modify values for the following parameter types: header, query, path, cookie.

In this example, we're using the parameters object to set custom values for path and header request parameters.

<OpenApiTryIt
  definitionId="petstore"
  operationId="deletePet"
  defaultExample="Cat"
  parameters={{
    path: {
      petId: 13
    },
    header: {
      api_key: "your123api456key789"
    }
  }}
/>

Add the options object

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

The OpenApiTryIt component supports the following options:

• events
• schemaExpansionLevel

In this example, we're adding the schemaExpansionLevel option to automatically expand all schema contents up to four levels. The events option creates a console log entry every time a request is sent from the component.

<OpenApiTryIt
  definitionId="petstore"
  operationId="deletePet"
  defaultExample="Cat"
  options={{
    schemaExpansionLevel: 4,
    events: { tryItSent: () => console.log('tryItSent') },
  }}
/>