Generate 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").
Valid API definition file(s) with
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
Serverobject (for example,
production...), only the first listed server will be included in auto-generated code samples.
Custom code samples directly added to the API definition using the
x-codeSamples specification extension have precedence over auto-generated ones.
Redocly Workflows user account and/or access to configuration files for Redocly Developer portal and API 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.
- If you manage your API definitions and documentation with Workflows, refer to the Workflows section.
- If you're using the Redocly configuration file with Workflows or building API documentation on-premise, use the API docs instructions.
- To include auto-generated code samples in your developer portal, refer to the Developer portal section.
Configure code samples
- Log into Workflows and select the API version for which you want to configure auto-generated code samples.
- From the Overview page, navigate to Settings > Features .
- On the Features page, expand the Generate code samples section.
- To enable code samples, select the desired language(s) from the list.
- Select Save to apply changes. This will trigger a new build.
Change order of languages
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 docs.
Custom labels for code sample tabs
By default, the names of selected languages are used as the tab captions in the Request samples section of your docs. To update it, select the pencil icon to the right of the language name, and set a custom label for the code sample tab.
Control appearance of generated code samples
To further control the appearance of generated code samples, you can enable the following settings as required:
- 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.
- 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 docs.
Skip optional parameters
- When selected, optional parameters
query paramsare not included in generated code samples.
Developer portal configuration
Your Developer portal can integrate API docs and contain API documentation for one or multiple API definitions.
To enable auto-generated code samples, you must modify the
.page.yamlconfiguration file for each of the definitions that should have the code samples.
.page.yamlconfiguration file, find or create the
settingsobject and add the
generateCodeSamplessettings like in the following example:
API docs configuration
To enable auto-generated code samples for API docs, you must modify the Redocly 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.
||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.
||Array of language config objects; indicates in which languages to generate code samples.|
||Can be one of
||Optional label for the generated code sample. Can be any string, e.g.
||When enabled, optional parameters cookies, headers and query params are not included in generated code samples. The default value is
||Skip optional properties in auto-generated payload samples. It also affects generated code samples. The default value is
||Do not show request
The following excerpt from the Redocly configuration 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.