To control the functionality of your API documentation, specify the configuration options depending on the selected usage method.
init function.theme.openapi section. 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
corsProxyUrlstring
Controls whether the requests sent from the Try it console should go through a CORS proxy. To use the Redocly CORS proxy, set https://cors.redoc.ly as the value. Alternatively, set the URL of your own CORS proxy server as the value. The hideTryItPanel option must be disabled for this feature to work.
Default "https://cors.redoc.ly"
ctrlFHijackboolean
Brings focus to the search bar when Control-F is pressed.
Default true
defaultSampleLanguagestring
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 generateCodeSamples.language.lang (for example, defaultSampleLanguage: 'JavaScript').
disableDeepLinksboolean
When set to true, disables the deep links functionality in Reference docs. Deep links are automatically created direct links to request parameters and request/response properties in all schemas in the middle panel, regardless of their nesting level. This functionality is enabled by default. To access a deep link, hover over a parameter or property in the middle panel and select the link icon to the left of the parameter/property name. Deep links are not supported in models and callbacks.
Default false
disableSearchboolean
Disables search indexing and hides the search box from the API documentation page.
Default false
disableTryItRequestUrlEncodingboolean
Disables request url encoding in the Try it console.
Default false
minCharacterLengthToInitSearchnumber>= 1
Sets the minimum amount of characters that need to be typed into the search dialog to initiate the search.
Default 3
disableSidebarboolean
If set to true, hides the navigation sidebar (the left panel). Starting with version 2.1.23, setting this option to false does not disable the search feature.
Default false
downloadDefinitionUrlstring
If the 'Download' button is visible in the API reference documentation (hideDownloadButton=false), the URL configured here will open when that button is selected. Provide it as an absolute URL with the full URI scheme.
expandDefaultServerVariablesboolean
Enables or disables expanding default server variables.
Default false
expandDefaultRequestboolean
Enables or disables expanding default request parameters panel.
Default true
expandDefaultResponseboolean
Enables or disables expanding default response content panel.
Default true
collapseRequestSamplePanelboolean
Enables or disables collapsing default request samples panel.
Default false
collapseResponseSamplePanelboolean
Enables or disables collapsing default response samples panel.
Default false
expandResponsesstring
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. expandResponses='200,201'. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.
expandSingleSchemaFieldboolean
Automatically expands the single field in a schema.
Default false
generateCodeSamplesobject
Controls options for generating code samples, including code sample languages.
generatedPayloadSamplesMaxDepthnumber
Controls how many schema levels to display in automatically generated payload samples.
Default 8
hideDownloadButtonboolean
Hides the 'Download' button for saving the API definition source file. This does not make the API definition private, it just hides the button.
Default false
hideHostnameboolean
If set to true, the protocol and hostname are not shown in the operation definition.
Default false
hideInfoSectionboolean
Hides the entire info section of the API definition when set to true.
Default false
hideLoadingboolean
Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.
Default false
hideLogoboolean
Hides the API logo defined in the x-logo specification extension.
Default false
hideFabboolean
Hides the floating action button (FAB) in mobile view.
Default false
hideRequestPayloadSampleboolean
Hides request payload examples.
Default false
hideRightPanelboolean
Hides the entire right panel when set to true.
Default false
hideSchemaPatternboolean
If set to true, the pattern is not shown in the schema.
Default false
hideOneOfDescriptionboolean
If set to true, the description for oneOf/anyOf object is not shown in the schema.
Default false
hideSchemaTitlesboolean
Hides the schema title next to to the type.
Default false
hideSingleRequestSampleTabboolean
Hides the request sample tab for requests with only one sample.
Default false
hideTryItPanelboolean
Disables the Try it console in the right panel.
Default false
showObjectSchemaExamplesboolean
Show object schema example in the properties, default false.
Default false
showAccessModeboolean
If set to `true', the schema component displays read-only and write-only flags.
Default false
htmlTemplatestring
Sets the path to the optional HTML file used to modify the layout of the reference docs page.
jsonSampleExpandLevelnumber or string>= 1
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 all that expands all levels.
Default 2
One of:
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 all that expands all levels.
>= 1
number>= 1
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 all that expands all levels.
Default 2
labelsobject
Sets the text for various labels displayed in schemas.
layoutstring
Controls the layout of the Reference docs page, affecting how the panels are displayed. Set the value to three-panel to use the default layout with the sidebar, middle panel, and right panel with code samples. Set the value to stacked to move the entire right panel into the middle panel. The stacked layout is identical to the layout activated by selecting the Change View button on the Reference docs page.
Default "three-panel"
Enum"stacked""three-panel"
maxDisplayedEnumValuesnumber
Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.
maxResponseHeadersToShowInTryItnumber>= 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 0, which displays all available headers.
Default 0
menuToggleboolean
If set to true, selecting an expanded item in the sidebar twice will collapse it.
Default true
mockServerobject
Allows to add mock server URL to the Try it console servers list.
nativeScrollbarsboolean
If set to true, the sidebar will use the native scrollbar instead of perfect-scroll. This is a scrolling performance optimization for big API definitions.
Default false
oAuth2RedirectURIstring
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.
onDeepLinkClickfunction
Configures custom behavior that will execute when users select a deep link. As a prerequisite, deep links must be enabled in Reference docs (disableDeepLinks must be set to false). Supported only in Reference docs CDN and in the React component.
onlyRequiredInSamplesboolean
Shows only required fields in request samples.
Default false
paginationstring
Controls how the API documentation should be paginated.
Default "none"
Enum Value Description nonepagination disabled, all content is rendered on a single long page; replaces deprecated layout.scope=all, routingStrategy=hash
each tag with a set of associated operations is rendered as a separate page; doesn't support operations without tags; replaces deprecated layout.scope=section, routingStrategy=browser
each tag and each operation are rendered on separate pages; replaces deprecated layout.scope=item, routingStrategy=browser
pathInMiddlePanelboolean
Shows the path link and HTTP verb in the middle panel instead of the right panel.
Default false
payloadSampleIdxnumber>= 0
If set, the payload sample will be inserted at the specified index. If there are N payload samples and the value configured here is bigger than N, the payload sample will be inserted last. Indexes start from 0.
Default 0
requestInterceptorfunction
Configures the request interceptor for the Try it console. As a prerequisite, the Try it console must be enabled in Reference docs (hideTryItPanel must be set to false). When configured, the interceptor can capture the request object and modify it according to specified criteria. Async usage is supported.
requiredPropsFirstboolean
Shows required properties in schemas first, ordered in the same order as in required array.
Default false
routingBasePathstring
Specifies the base path when reference docs are hosted at something other than the root (/) of their domain.
markdownHeadingsAnchorLevelnumber
Controls what level of headings are having anchors and renders as a section from markdown files or descriptions.
Default 2
samplesTabsMaxCountnumber
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.
Default 5
schemaDefinitionsTagNamestring
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 x-tags specification extension.
schemaExpansionLevelstring or number
Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemaExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.
Default 0
One of:
Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemaExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.
string
Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemaExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.
Default 0
scrollYOffsetstring or number
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 scrollYOffset value in any of the following ways:
Default 0
One of:
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 scrollYOffset value in any of the following ways:
string
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 scrollYOffset value in any of the following ways:
Default 0
searchAutoExpandboolean
If set to true, all response schemas are automatically expanded when displaying the results for a search query. Phrases matching the search query are highlighted in expanded schemas.
Default true
searchFieldLevelBoostnumber(float)
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.
Default 0.95
searchMaxDepthnumber
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.
Default 1
searchModestring
Controls the search indexing mode. Supported values: 'default'; 'path-only' (will index and search only the operation paths).
Default "default"
Enum"default""path-only"
searchOperationTitleBoostnumber
Specifies the boost factor for search terms found in operation titles. The bigger the value, the higher searches will rank.
Default 4
searchTagTitleBoostnumber
Specifies the boost factor for search terms found in tag titles.
Default 8
sendXUserAgentInTryItany
Enables adding header X-User-Agent: Redocly Try it API console to every request made from Try it console.
NOTE: make sure to add X-User-Agent to your Access-Control-Allow-Headers CORS header.
Default false
showWebhookVerbboolean
When set to true, shows the HTTP request method for webhooks in operations and in the sidebar.
Default false
showChangeLayoutButtonboolean
When set to true, displays the Change Layout button in the upper right corner of the Reference docs page. Selecting this button moves the middle panel to the center of the page, and places the contents of the right panel (code samples and the API console) into the middle panel.
Default true
showExtensionsboolean or string
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 true, all specification extensions are shown.
Default false
One of:
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 true, all specification extensions are shown.
boolean
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 true, all specification extensions are shown.
Default false
preserveOriginalExtensionsNameboolean
Allows to preserve the original name of the schema extension ('x-' prefix).
Default false
showNextButtonboolean
Controls whether to show the 'Next to ...' button at the end of each section when pagination is enabled.
Default true
showRightPanelToggleboolean
When set to true, displays the Hide Samples button in the upper right corner of the Reference docs page. Selecting this button hides the entire right panel with code samples and the API console. When the Change View button is enabled and selected, the Hide Samples button is not visible on the page.
Default true
showSecuritySchemeTypeboolean
Shows authorization type on the Security panel
Default false
hideSecuritySectionboolean
Hides the Security panel section.
Default false
sidebarLinksobject
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.
sideNavStylestring
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. The 'path-only' style shows only the path. Available only in Redoc CE.
Default "summary-only"
Enum"summary-only""path-first""id-only""path-only"
simpleOneOfTypeLabelboolean
Shows only unique oneOf types in the label without titles.
Default false
sortEnumValuesAlphabeticallyboolean or string
When set to true, sorts all enum values in all schemas alphabetically.
One of:
When set to true, sorts all enum values in all schemas alphabetically.
boolean
When set to true, sorts all enum values in all schemas alphabetically.
sortOperationsAlphabeticallyboolean or string
When set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically.˙
One of:
When set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically.˙
boolean
When set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically.˙
sortPropsAlphabeticallyboolean
When set to true, sorts properties in all schemas alphabetically.
Default false
sortTagsAlphabeticallyboolean
When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags will be sorted alphabetically in the middle panel, not the operations associated with each tag. To sort operations alphabetically as well, you must set sortOperationsAlphabetically to true.
Default false
unstable_ignoreMimeParametersboolean
Applies a workaround to ignore charset=utf in mime-type.
Default false
untrustedDefinitionboolean
If set to true, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.
Default false
hooksobject
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 redocly.yaml. You can provide them when using Reference docs as JavaScript library from CDN
eventsobject
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 redocly.yaml. You can provide them when using Reference docs as JavaScript library from CDN
noAutoAuthbooleanDeprecated
Deprecated configuration option.
Default false
routingStrategystringDeprecated
Deprecated configuration option.
showConsolebooleanDeprecated
Deprecated configuration option. Use hideTryItPanel instead.
Default true
suppressWarningsbooleanDeprecated
Deprecated configuration option.
unstable_externalDescriptionstringDeprecated
Deprecated configuration option.
Example configuration with JavaScript libraryRedoclyReferenceDocs.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'
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4