OpenAPI Code Sample Tag Redocly Custom Tag

The openapi-code-sample tag renders sample code snippets directly in your documentation, showing users how to interact with API operations defined in your OpenAPI description. By default, both request and response examples are displayed.

Syntax and usage

To use the tag, pass the filepath of your OpenAPI description using the descriptionFile attribute and a reference to the specific operation using either operationId or pointer. You can also use additional attributes to configure the code sample element rendered in the document.

With operationId:

{% openapi-code-sample
  descriptionFile="../../../demo/openapi/museum-api.yaml"
  operationId="getMuseumHours"
/%}

With pointer:

{% openapi-code-sample
  descriptionFile="../../../demo/openapi/museum-api.yaml"
  pointer="/paths/~1museum-hours/get"
/%}

Attributes

Environment variables

The environment variables available in the code sample correspond with your security schemes. The name of the security scheme must be used in the variable. Here's a list of available variables:

• Basic auth = SchemeName_username and SchemeName_password
• JWT token or OAuth token = SchemeName_token
• OAuth credentials = SchemeName_client_id and SchemeName_client_secret
• API key auth does not have a suffix, so the variable is SchemeName

By prefilling security credentials for logged in users, you can provide code samples that are fully ready to execute.

For example:

{% openapi-code-sample
  descriptionFile="../../../demo/openapi/museum-api.yaml"
  operationId="createSpecialEvent"
  environment="https://api.fake-museum-example.com/v1"
  environments={
    "https://api.fake-museum-example.com/v1": {
      "MuseumOAuth_token": $user-props.token,
    }
  }
/%}

Examples

Basic usage

By default, the tag will render a code sample in multiple languages for a specific API operation, as in the following example:

{% openapi-code-sample
  descriptionFile="../../../demo/openapi/museum-api.yaml"
  operationId="createSpecialEvent"
/%}

curl -i -X POST \
  -u <username>:<password> \
  https://api.fake-museum-example.com/v1.1/special-events \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Mermaid Treasure Identification and Analysis",
    "location": "Under the seaaa 🦀 🎶 🌊.",
    "eventDescription": "Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.",
    "dates": [
      "2023-09-05",
      "2023-09-08"
    ],
    "price": 0
  }'

{
  "eventId": "dad4bce8-f5cb-4078-a211-995864315e39",
  "name": "Mermaid Treasure Identification and Analysis",
  "location": "Under the seaaa 🦀 🎶 🌊.",
  "eventDescription": "Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.",
  "dates": [
    "2023-09-05",
    "2023-09-08"
  ],
  "price": 30
}

With single language

You can restrict the code sample to a specific language using the language attribute. The following example limits the code sample to JavaScript:

{% openapi-code-sample
  descriptionFile="../../../demo/openapi/museum-api.yaml"
  operationId="createSpecialEvent"
  language="JavaScript"
/%}

const resp = await fetch(
  `https://redocly.com/_mock/demo/openapi/museum-api/special-events`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Basic ' + btoa('<username>:<password>')
    },
    body: JSON.stringify({
      name: 'Mermaid Treasure Identification and Analysis',
      location: 'Under the seaaa 🦀 🎶 🌊.',
      eventDescription: 'Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.',
      dates: [
        '2023-09-05',
        '2023-09-08'
      ],
      price: 0
    })
  }
);

const data = await resp.json();
console.log(data);

{
  "eventId": "dad4bce8-f5cb-4078-a211-995864315e39",
  "name": "Mermaid Treasure Identification and Analysis",
  "location": "Under the seaaa 🦀 🎶 🌊.",
  "eventDescription": "Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.",
  "dates": [
    "2023-09-05",
    "2023-09-08"
  ],
  "price": 30
}

With pre-defined values

You can use various attributes to provide values that resolve to the rendered element. The following example includes pre-defined parameters and environment variables.

{% openapi-code-sample
  descriptionFile="../../../demo/openapi/museum-api.yaml"
  operationId="deleteSpecialEvent"
  language="curl"
  parameters={
    path: {
      eventId: "dad4bce8-f5cb-4078-a211-995864315e39"
    }
  }
  environment="https://api.fake-museum-example.com/v1"
  environments={
    "https://api.fake-museum-example.com/v1": {
      "MuseumPlaceholderAuth_username": "custom-username",
      "MuseumPlaceholderAuth_password": "custom-password"
    }
  }
/%}

curl -i -X DELETE \
  -u custom-username:custom-password \
  https://redocly.com/_mock/demo/openapi/museum-api/special-events/dad4bce8-f5cb-4078-a211-995864315e39

{
  "type": "object",
  "title": "Validation failed"
}

Best practices

Customize for flexibility

The various attributes give you a lot of flexibility to customize the code sample, allowing you to meet a more diverse range of API scenarios. You can use them to tailor the code samples to the specific needs of your users.

Document code samples

Pair code samples with comprehensive documentation. Explain the purpose of each sample, the expected behavior, and any modifications that users might need to make. This way you can help your users to successfully build with your API.