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

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

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

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

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.

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

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

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

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