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 does not render if you don't include the required properties in your code block.
Props
Name | Type | Description |
---|---|---|
id | string | Required when you want to chain multiple requests together or a request and an explanation which uses the response. |
needs | array | Required 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`. |
placeholder | string | A function that returns a React component that is displayed until the needs are met. Use in combination with `needs`. |
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. |
operationId* | string | Indicates 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* | string | JSON 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`. |
defaultExample | string | Specifies 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`. |
onlyDefaultExample | boolean | When 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 |
properties | object | Use this object to set request body properties in the request example. |
parameters | object | Use this object to set request parameter values. |
options | object | Use Reference docs configuration options in this object to customize the appearance and behavior of the component. |
onResponse | object | Optional 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. |
serverVariables | object | Override the default server variables by providing an map of variable name and corresponding object with new default value. |
securityDefaults | object | Optional 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.
<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 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.
<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.
<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') },
}}
/>