Last updated 1 month ago

Generating code samples automatically

Redocly can automatically generate code samples in supported languages based on your API definition. You can control the display of optional properties and parameters, and hide request payload samples. The list of supported languages indicates currently supported version(s) for each language.

Auto-generated code samples are not available in Redoc (the "community edition").

Prerequisites

  1. Valid API definition file(s) with requestBody objects

The content of auto-generated code samples is affected by the API definition in the following ways:

  • If your API definition has several security schemes defined as alternatives in your Security Scheme object, only the first one will be included in auto-generated code samples. If the security schemes are defined as mandatory in every request, they will all be included.
  • If your API definition lists several servers in the Server object (for example, default, development, production...), only the first listed server will be included in auto-generated code samples.
Note

Custom code samples directly added to the API definition using the x-codeSamples specification extension have precedence over auto-generated ones. For instance, if your API definition already contains a JavaScript sample, and you enable auto-generated JavaScript samples, your reference docs will only show the custom sample from the API definition.

  1. Redocly Workflows user account and/or access to configuration files for Redocly Developer portal and Reference docs

To enable auto-generated code samples, you must specify in which languages to generate them. The configuration procedure depends on the Redocly product you're using.

Configure code samples in Workflows

  1. In your Redocly Workflows organization, access the Reference docs tab and select the reference docs for which you want to configure auto-generated code samples.
  2. In the Settings tab, select API reference settings and navigate to the Code samples section.

Reference docs > Settings > API reference settings > Code samples

  1. The Generate code samples section lists currently supported languages for auto-generating code samples in your reference docs. To enable code samples, select the desired language(s) in this list.
  2. You can change the order of languages by dragging them up or down in the list. This order affects the order of tabs (from left to right) in the Request samples section of your reference docs.
  3. By default, the names of selected languages are used as the tab captions in the Request samples section of your reference docs. To change that, select the pencil icon to the right of the language name, and set a custom label for the code sample tab.
  4. Optionally, enable the following settings to further control the appearance of generated code samples:
  5. Skip optional properties in auto-generated payload samples - When selected, only required fields are included in auto-generated code samples and in request payload samples.
  6. Do not show request payload tab - When selected, the code sample for the request payload is not displayed in the Request samples section of your reference docs.
  7. Skip optional parameters - When selected, optional parameters cookies, headers and query params are not included in generated code samples.
  8. Select Save settings to apply changes.

Configure code samples in Developer portal

Your Developer portal can integrate with Reference docs and contain API reference documentation for one or multiple API definitions.

To enable auto-generated code samples, you must modify the .page.yaml configuration file for each of the definitions that should have the code samples.

In the .page.yaml configuration file, find or create the settings object and add the generateCodeSamples settings like in the following example:

type: reference-docs
definitionId: acme
settings:
  generateCodeSamples:
    languages:
     - lang: JavaScript
       label: JS
     - lang: C#
     - lang: Java

This particular example will enable generating code samples for JavaScript, C#, and Java. For details on how to enable other languages, consult the Reference docs instructions.

Configure code samples in Reference docs

To enable auto-generated code samples for Reference docs, you must modify the .redocly.yaml configuration file.

The following options refer to auto-generated code samples. They correspond to the options available in Workflows, and can be used in the .page.yaml configuration file(s) for Developer portal.

Option Description
generateCodeSamples The object that controls the options for auto-generating code samples.
Note that custom code samples directly added to the API definition using the x-codeSamples specification extension have precedence over auto-generated ones.
generateCodeSamples.languages Array of language config objects; indicates in which languages to generate code samples.
generateCodeSamples.languages.lang Can be one of curl, Node.js, JavaScript, Python, C#, Java, Java+Apache.
generateCodeSamples.languages.label Optional label for the generated code sample. Can be any string, e.g. JS or Awesome Language. When configured here, the label is displayed insted of lang as the tab caption in the Request samples section of your reference docs.
generateCodeSamples.skipOptionalParameters When enabled, optional parameters cookies, headers and query params are not included in generated code samples. The default value is false.
onlyRequiredInSamples Skip optional properties in auto-generated payload samples. It also affects generated code samples. The default value is false.
hideRequestPayloadSample Do not show request Payload example. The default value is false.

The following excerpt from a .redocly.yaml file illustrates how to enable auto-generated code samples for several languages, add a custom label to one of them, and hide the request payload tab from the API documentation.

referenceDocs:
  htmlTemplate: ./docs/index.html
  generateCodeSamples:
    languages:
      - lang: curl
        label: Custom label
      - lang: Python
      - lang: JavaScript
  hideRequestPayloadSample: true