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.
- 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 Server object (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
- 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.
- If you manage your API definitions and build documentation with Workflows, use Workflows instructions.
- If you're using a custom
.redocly.yamlfile with Workflows or building API documentation on-premise, use Reference docs instructions.
- To include auto-generated code samples in your developer portal, use Developer portal instructions.
- 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.
- In the Settings tab, select API reference settings and navigate to the Code samples section.
- 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.
- 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.
- 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.
- Optionally, enable the following settings to further control the appearance of generated code samples:
- 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 reference docs.
- Skip optional parameters - When selected, optional parameters
query paramsare not included in generated code samples.
- Select Save settings to apply changes.
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.
.page.yaml configuration file, find or create the
settings object and add the
generateCodeSamples settings like in the following example:
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.
||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 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.