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

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

Loading...

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

Copy
Copied
<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 does not render if you don't include the required properties in your code block.

Props

NameTypeDescription
idstringRequired when you want to chain multiple requests together or a request and an explanation which uses the response.
needsarrayRequired when you need another try it request completed prior to this try it request. Supply an array of id's from the predecessor try it requests. Use in combination with `placeholder`.
placeholderstringA function that returns a React component that is displayed until the needs are met. Use in combination with `needs`.
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.
operationId*stringIndicates the operation from the specified API definition that will be used in the component. The value must match one of the `operationId` fields from the `definitionId` API definition. This property is mutually exclusive with `pointer`.
pointer*stringJSON pointer to an operation 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: `#/paths/pathname/operation` (e.g. `#/paths/examplePath/get`). This property is mutually exclusive with `operationId`.
defaultExamplestringSpecifies which request example will be used as the default. The value must match the name of one request body `examples` object from the operation specified by `operationId` or `pointer`. If the specified example does not exist, the component will display a warning message and use the first example listed in the API definition. This property must be set if you want to use `onlyDefaultExample`.
onlyDefaultExamplebooleanWhen set to true, only the default request example is displayed in the component, and the example selection menu is hidden. This property requires you to set a non-empty value for `defaultExample`. Default value: false
propertiesobjectUse this object to set request body properties in the request example.
parametersobjectUse this object to set request parameter values.
optionsobjectUse Reference docs configuration options in this object to customize the appearance and behavior of the component.
onResponseobjectOptional callback that can be used to work with the response and request data after a successful request (for example, to forward the data to a log). When defined, the callback is invoked after the response is received in the component.
serverVariablesobjectOverride the default server variables by providing an map of variable name and corresponding object with new default value.
securityDefaultsobjectOptional property that can be used to specify default values for security schemes in example requests.

Usage examples

Set the default example

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

If an example named "Cat" exists for the specified operation, it displays automatically.

Copy
Copied
<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.

Copy
Copied
<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 is 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.

Copy
Copied
<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 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.

Copy
Copied
<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.

Copy
Copied
<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.

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