Configuration options for API docs
Users of open source Redoc should refer to the Redoc configuration documentation.
To control the functionality of your API documentation, specify the configuration options depending on the selected usage method.
- When using a JavaScript library, specify the options in the second argument of the
initfunction. - When using our Workflows hosted service or our CLI for on-premise deployments, we recommend specifying the options in the Redocly configuration file. In this case, specify the options in the
theme.openapisection. Note that live configuration in Workflows may be used to override the Redocly configuration file.
Expand the theme object openapi schema below to show all supported configuration options. The premium version of Redocly API docs can use all of the listed options. The Redoc Community Edition (free and open source version) can only use the options marked as supported. All of the listed options are compatible with the Redocly configuration file used in the API registry and Redocly CLI, and in Developer portal.
theme object openapi schema
| corsProxyUrl | string Default: "https://cors.redoc.ly" Controls whether the requests sent from the Try it console should go through a CORS proxy. To use the Redocly CORS proxy, set | ||||||||
| ctrlFHijack | boolean Default: true Brings focus to the search bar when Control-F is pressed. | ||||||||
| defaultSampleLanguage | string Specifies the code sample language tab that will be selected by default in all code samples panels. When configured, this selection is sticky, which means it's preserved between page reloads. The language specified here must match one of the values from | ||||||||
| disableDeepLinks | boolean Default: false When set to | ||||||||
| disableSearch | boolean Default: false Disables search indexing and hides the search box from the API documentation page. | ||||||||
| disableTryItRequestUrlEncoding | boolean Default: false Disables request url encoding in the Try it console. | ||||||||
| minCharacterLengthToInitSearch | number >= 1 Default: 3 Sets the minimum amount of characters that need to be typed into the search dialog to initiate the search. | ||||||||
| disableSidebar | boolean Default: false If set to | ||||||||
| downloadDefinitionUrl | string If the 'Download' button is visible in the API reference documentation ( | ||||||||
| expandDefaultServerVariables | boolean Default: false Enables or disables expanding default server variables. | ||||||||
| expandDefaultRequest | boolean Default: true Enables or disables expanding default request parameters panel. | ||||||||
| expandDefaultResponse | boolean Default: true Enables or disables expanding default response content panel. | ||||||||
| collapseRequestSamplePanel | boolean Default: false Enables or disables collapsing default request samples panel. | ||||||||
| collapseResponseSamplePanel | boolean Default: false Enables or disables collapsing default response samples panel. | ||||||||
| expandResponses | string Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, e.g. | ||||||||
| expandSingleSchemaField | boolean Default: false Automatically expands the single field in a schema. | ||||||||
object Controls options for generating code samples, including code sample languages. | |||||||||
| generatedPayloadSamplesMaxDepth | number Default: 8 Controls how many schema levels to display in automatically generated payload samples. | ||||||||
| hideDownloadButton | boolean Default: false Hides the 'Download' button for saving the API definition source file. This does not make the API definition private, it just hides the button. | ||||||||
| hideHostname | boolean Default: false If set to | ||||||||
| hideInfoSection | boolean Default: false Hides the entire info section of the API definition when set to | ||||||||
| hideLoading | boolean Default: false Hides the loading animation. Does not apply to CLI or Workflows-rendered docs. | ||||||||
| hideLogo | boolean Default: false Hides the API logo defined in the x-logo specification extension. | ||||||||
| hideFab | boolean Default: false Hides the floating action button (FAB) in mobile view. | ||||||||
| hideRequestPayloadSample | boolean Default: false Hides request payload examples. | ||||||||
| hideRightPanel | boolean Default: false Hides the entire right panel when set to | ||||||||
| hideSchemaPattern | boolean Default: false If set to | ||||||||
| hideOneOfDescription | boolean Default: false If set to | ||||||||
| hideSchemaTitles | boolean Default: false Hides the schema title next to to the type. | ||||||||
| hideSingleRequestSampleTab | boolean Default: false Hides the request sample tab for requests with only one sample. | ||||||||
| hideTryItPanel | boolean Default: false Disables the Try it console in the right panel. | ||||||||
| showObjectSchemaExamples | boolean Default: false Show object schema example in the properties, default false. | ||||||||
| showAccessMode | boolean Default: false If set to `true', the schema component displays read-only and write-only flags. | ||||||||
| htmlTemplate | string Sets the path to the optional HTML file used to modify the layout of the reference docs page. | ||||||||
number or string >= 1 Default: 2 Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value | |||||||||
object Sets the text for various labels displayed in schemas. | |||||||||
| layout | string Default: "three-panel" Controls the layout of the Reference docs page, affecting how the panels are displayed. Set the value to | ||||||||
| maxDisplayedEnumValues | number Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed. | ||||||||
| maxResponseHeadersToShowInTryIt | number >= 0 Default: 0 Specify the number of response headers that will be visible in the Try it console. If there are more headers than the specified number, they will be collapsed and accessible by selecting the Show more link. The default value is | ||||||||
| menuToggle | boolean Default: true If set to | ||||||||
object Allows to add mock server URL to the Try it console servers list. | |||||||||
| nativeScrollbars | boolean Default: false If set to | ||||||||
| noAutoAuth | boolean Deprecated Default: false Deprecated configuration option. | ||||||||
| oAuth2RedirectURI | string Allows specifying the URI of the oAuth2 redirect page. If you're using Reference docs with Workflows, this value is automatically set and there is usually no need to modify it. | ||||||||
| onDeepLinkClick | function Configures custom behavior that will execute when users select a deep link. As a prerequisite, deep links must be enabled in Reference docs ( | ||||||||
| onlyRequiredInSamples | boolean Default: false Shows only required fields in request samples. | ||||||||
| pagination | string Default: "none" Controls how the API documentation should be paginated.
| ||||||||
| pathInMiddlePanel | boolean Default: false Shows the path link and HTTP verb in the middle panel instead of the right panel. | ||||||||
| payloadSampleIdx | number >= 0 Default: 0 If set, the payload sample will be inserted at the specified index. If there are | ||||||||
| requestInterceptor | function Configures the request interceptor for the Try it console. As a prerequisite, the Try it console must be enabled in Reference docs ( | ||||||||
| requiredPropsFirst | boolean Default: false Shows required properties in schemas first, ordered in the same order as in required array. | ||||||||
| routingBasePath | string Specifies the base path when reference docs are hosted at something other than the root ( | ||||||||
| routingStrategy | string Deprecated Deprecated configuration option. | ||||||||
| markdownHeadingsAnchorLevel | number Default: 2 Controls what level of headings are having anchors and renders as a section from markdown files or descriptions. | ||||||||
| samplesTabsMaxCount | number Default: 5 Controls how many code sample tabs are displayed in the right panel by default. If your API definition has code samples for more languages than configured here, their tabs are automatically grouped into a 'show more' menu at the end of the tab list. | ||||||||
| schemaDefinitionsTagName | string If value is set, it associates all of the schemas with the designated tag name. The schemas then render and display in the sidebar navigation (with that associated tag name). To display only specific schemas, use the | ||||||||
string or number Default: 0 Specifies whether to automatically expand schemas in Reference docs. Set it to | |||||||||
string or number Default: 0 Specifies a vertical scroll-offset. This is useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc. Note that you can specify the
| |||||||||
| searchAutoExpand | boolean Default: true If set to | ||||||||
| searchFieldLevelBoost | number <float> Default: 0.95 Specifies the boost factor for search terms found in fields at a specific level. If this value is lower than 1, search results found on deeper levels will rank lower. | ||||||||
| searchMaxDepth | number Default: 1 Controls the search indexing depth for your Reference docs. Set the value to a number from 1 to 10 to specify the maximum level of nested references that should be included in the search index. In this context, 'nested references' means content added to the API definition with $ref. | ||||||||
| searchMode | string Default: "default" Controls the search indexing mode. Supported values: 'default'; 'path-only' (will index and search only the operation paths). | ||||||||
| searchOperationTitleBoost | number Default: 4 Specifies the boost factor for search terms found in operation titles. The bigger the value, the higher searches will rank. | ||||||||
| searchTagTitleBoost | number Default: 8 Specifies the boost factor for search terms found in tag titles. | ||||||||
| sendXUserAgentInTryIt | any Default: false Enables adding header NOTE: make sure to add | ||||||||
| showWebhookVerb | boolean Default: false When set to | ||||||||
| showChangeLayoutButton | boolean Default: true When set to | ||||||||
| showConsole | boolean Deprecated Default: true Deprecated configuration option. Use | ||||||||
boolean or string Default: false Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to | |||||||||
| preserveOriginalExtensionsName | boolean Default: false Allows to preserve the original name of the schema extension ('x-' prefix). | ||||||||
| showNextButton | boolean Default: true Controls whether to show the 'Next to ...' button at the end of each section when pagination is enabled. | ||||||||
| showRightPanelToggle | boolean Default: true When set to | ||||||||
| showSecuritySchemeType | boolean Default: false Shows authorization type on the Security panel | ||||||||
| hideSecuritySection | boolean Default: false Hides the Security panel section. | ||||||||
object Configures custom links that will be added to the navigation sidebar at the top (before the info section) or at the end. Link to any internal or external resource. For each item in the array, define the label, link, and target. | |||||||||
| sideNavStyle | string Default: "summary-only" Defines the style of navigation sidebar items (in the left panel). The default style is 'summary-only'. The 'path-first' style shows the path first with the summary underneath and the 'id-only' style shows the operation id if provided, otherwise path. | ||||||||
| simpleOneOfTypeLabel | boolean Default: false Shows only unique | ||||||||
boolean or string When set to | |||||||||
boolean or string When set to | |||||||||
| sortPropsAlphabetically | boolean Default: false When set to | ||||||||
| sortTagsAlphabetically | boolean Default: false When set to | ||||||||
| suppressWarnings | boolean Deprecated Deprecated configuration option. | ||||||||
| theme | object Theming options that control the style of the generated API documentation. Consult the full list of supported options. | ||||||||
| unstable_externalDescription | string Deprecated Deprecated configuration option. | ||||||||
| unstable_ignoreMimeParameters | boolean Default: false Applies a workaround to ignore | ||||||||
| untrustedDefinition | boolean Default: false If set to | ||||||||
object Extension hooks into Reference engine with custom JavaScript code. Allows injecting UI elements into different points or overriding some core functionality. NOTE: These options contain custom JavaScript, so they can't be used in | |||||||||
object Events hooks to get notified about various user events in Reference docs. Useful for analytics purposes. Each event provides information about a specific event as well as some basic information: eventType: string; resource: string; action: string; operationId?: string; operationPath: string; operationHttpVerb: string; operationSummary?: string; NOTE: These options contain custom JavaScript, so they can't be used in |
Example configuration with JavaScript library
RedoclyReferenceDocs.init( '<path to api definition>', { licenseKey: '<license-key.here>', pagination: 'section', generateCodeSamples: { languages: [{ lang: 'curl' }, { lang: 'Node.js' }, { lang: 'JavaScript', label: 'JS' }], skipOptionalParameters: true, }, theme: { colors: { primary: { main: '#6EC5AB', }, }, typography: { fontFamily: `"museo-sans", 'Helvetica Neue', Helvetica, Arial, sans-serif`, fontSize: '15px', lineHeight: '1.5', code: { code: '#87E8C7', backgroundColor: '#4D4D4E', }, }, menu: { backgroundColor: '#ffffff', }, }, hooks: { BeforeOperationSummary: (operation) => ({ html: `<i>ID: ${operation.operationId}</i>` }), }, }, document.querySelector('#redoc_container') );
Example Redocly configuration file
The Redocly configuration file is compatible with the CLI and our hosted API registry.
theme openapi: licenseKey: <license-key-here> pagination: section theme: sidebar: backgroundColor: '#ffffff'
Live configuration
If you're using Workflows to build your API docs, you can override any existing configuration in redocly.yaml by using the Live configuration editor.
On the API registry page, select your API version.
From the Overview page of the selected API version, access the Settings tab.
On the Settings page, select Features, and then select the Configuration button. This opens the live configuration editor.
Any settings you enter in the live configuration editor are merged with the existing redocly.yaml settings. Live configuration settings have higher priority and override the configuration file settings in case of conflict.
To apply changes you've made in the live configuration editor, select Save. This triggers a new build in the registry.