OpenApiCodeSample

With the OpenApiCodeSample component, you can add code samples from your API definitions to MDX pages in your portal. When the component is included in an MDX page, it is rendered to look exactly like the Request samples section in Reference pages.

The component displays multiple tabs for code sample languages and the content type selection dropdown. Auto-generated code samples are also supported by the component. Enable them by adding generateCodeSamples to the options object in the component.

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

$form = new \PetStore\Entities\Pet();
$form->setPetType("Dog");
$form->setName("Rex");
// set other fields
try {
    $pet = $client->pets()->create($form);
} catch (UnprocessableEntityException $e) {
    var_dump($e->getErrors());
}

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

Copy
Copied
<OpenApiCodeSample
  definitionId="petstore"
  operationId="addPet"
  defaultLanguage="PHP"
/>

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

NameTypeDefaultDescription
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`.
onlyDefaultExamplebooleanfalseWhen 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`.
propertiesobjectUse this object to preset request body properties that will be displayed by default in the component.
parametersobjectUse this object to preset request parameter values that will be displayed by default in the component.
optionsobjectUse Reference docs configuration options in this object to customize the appearance and behavior of the component.
defaultLanguagestringSpecifies which code sample language will be treated as the default. The tab for this language will be preselected in the component, and the selection will be preserved between page reloads. For code samples added with *x-codeSamples*, the value here must match the value of *lang*. For auto-generated code samples, they must be configured in the `options` object, and the value here must match one of the values from *generateCodeSamples.language.lang*. If the specified language is incorrect or not supported, the component will display an error.
defaultMimeTypestringSets the default MIME type for code samples in the component. The specified MIME type is selected by default in all code sample tabs.
onlyDefaultMimeTypebooleanSpecifies that only the default MIME type should be visible for code samples in the component. If it is set to *true* and the default MIME type is configured, the MIME type dropdown is hidden in code sample tabs. If it is set to *true* and the default MIME type is not configured, the first available MIME type from the API definition is preselected, and the dropdown is visible in code sample tabs.

Usage examples

Set the default MIME type

We're using the defaultMimeType property to specify the MIME type that will be preselected in all code sample tabs in the component. Because the onlyDefaultMimeType property is enabled in this example, the dropdown with other MIME types will be hidden.

Copy
Copied
<OpenApiCodeSample
  definitionId="petstore"
  operationId="addPet"
  defaultLanguage="JavaScript"
  onlyDefaultMimeType
  defaultMimeType="application/json"
/>

Add the options object

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

The OpenApiCodeSample component supports the following options:

  • events
  • generateCodeSamples
  • generatedPayloadSamplesMaxDepth
  • hideRequestPayloadSample
  • hideSingleRequestSampleTab
  • jsonSampleExpandLevel
  • onlyRequiredInSamples
  • payloadSampleIdx
  • schemaExpansionLevel

In this example, we're adding some of the supported configuration options to the options object.

As a result, the component will be displayed without the Payload tab, and with JavaScript and PHP tabs containing automatically generated code samples. Additionally, every action of switching to a different language tab will be logged to the console.

Copy
Copied
<OpenApiCodeSample
  definitionId="petstore"
  operationId="addPet"
  defaultLanguage="JavaScript"
  options={{
    hideRequestPayloadSample: true,
    events: {codeSamplesLanguageSwitch: () => console.log('codeSamplesLanguageSwitch')},
    generateCodeSamples: {
      languages: [{
        lang: 'JavaScript'
      },
      {
        lang: 'PHP'
      }]
    }
  }}
/>

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 some of the fields in the request body.

The component will use these values in all visible tabs.

Copy
Copied
<OpenApiCodeSample
  definitionId="petstore"
  operationId="addPet"
  defaultLanguage="JavaScript"
  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.

The component will use these custom values in all visible tabs.

Copy
Copied
<OpenApiCodeSample
  definitionId="petstore"
  operationId="deletePet"
  defaultLanguage="JavaScript"
  parameters={{
    path: {
      petId: 13
    },
    header: {
      api_key: "your123api456key789"
    }
  }}
/>