Last updated

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.

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="../../openapi/museum-api.yaml"
  operationId="getMuseumHours"
/%}

With pointer:

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

Attributes

AttributeTypeDescription
descriptionFileStringREQUIRED. A path to an OpenAPI description.
operationIdStringID of the operation inside the OpenAPI description. Required if pointer is not specified.
pointerStringPointer to an operation inside the OpenAPI description. Required if operationId is not specified. Slashes used on endpoints must be encoded with ~1 -- for example, /paths/~1some-endpoint/post.
exampleKeyStringKey specifying which example to use. Must match the key used for an operation's example in the OpenAPI description.
languageStringLimits the code sample to a specific language. Works with the following values (case sensitive): Payload, curl, C#, Node.js, JavaScript, Python, R, Ruby, PHP, Go, Java.
parametersObjectCustom parameters to use for the OpenAPI operation code sample. Accepts values for header and query.
requestBodyObjectDefines an inline request body to use. Replaces any request body in the code sample.
environmentStringLimits the environment picker in the code sample to a specific server defined in the OpenAPI description.
environmentsObjectProvide environment variables that resolve to your code sample. Variables are based on your OpenAPI description's securitySchemes. See environment variables.

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="../../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="../../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
  }'

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="../../openapi/museum-api.yaml"
  operationId="createSpecialEvent"
  language="JavaScript"
/%}

const resp = await fetch(
  `https://api.fake-museum-example.com/v1.1/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);

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="../../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://api.fake-museum-example.com/v1.1/special-events/dad4bce8-f5cb-4078-a211-995864315e39

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

Code samples should be paired with comprehensive documentation. You should explain the purpose of each sample, the expected behavior, and any modifications that users might need to make. This will help users more successfully build with your API.

 
Next page