Last updated 1 month ago

Configuration options for Reference docs

To control the appearance and the functionality of your API reference documentation, specify the configuration options under referenceDocs depending on the selected usage method.

When using a JavaScript library, specify the options in the second argument of the init function. If you're using our Workflows/hosted service or our CLI for on-premise deployments, we recommend specifying the options in a .redocly.yaml configuration file.

Expand the referenceDocs schema below to show all supported configuration options. The premium version of Redocly Reference 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 Reference docs configuration in OpenAPI CLI and in Developer portal.

referenceDocs schema

corsProxyUrl
string

Controls whether the requests sent from the API Console (the Try it functionality) 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 showConsole option must be enabled for this feature to work.

ctrlFHijack
boolean
Default: false

Brings focus to the search bar when Control-F is pressed.

disableSearch
boolean
Default: false

Disables search indexing and hides the search box from the API documentation page. Supported in Redoc CE.

disableSidebar
boolean
Default: false

If set to true, hides the navigation sidebar (the left panel).

downloadSpecUrl
string

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.

expandDefaultServerVariables
boolean
Default: false

Enables or disables expanding default server variables. Supported in Redoc CE.

expandResponses
string
Default: "200,201"

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. Supported in Redoc CE.

expandSingleSchemaField
boolean
Default: false

Automatically expands the single field in a schema. Supported in Redoc CE.

object

Controls options for generating code samples, including code sample languages.

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. Supported in Redoc CE.

hideHostname
boolean
Default: false

If set to true, the protocol and hostname are not shown in the operation definition. Supported in Redoc CE.

hideInfoSection
boolean
Default: false

Hides the entire info section of the API definition when set to true.

hideLoading
boolean
Default: false

Hides the loading animation. Does not apply to CLI or Workflows-rendered docs. Supported in Redoc CE.

hideLogo
boolean
Default: false

Hides the API logo defined in the x-logo specification extension.

hideRequestPayloadSample
boolean
Default: false

Hides request payload examples. Supported in Redoc CE.

hideSchemaPattern
boolean
Default: false

If set to true, the pattern is not shown in the schema. Supported in Redoc CE.

hideSchemaTitles
boolean
Default: false

Hides the schema title next to to the type. Supported in Redoc CE.

hideSingleRequestSampleTab
boolean
Default: false

Hides the request sample tab for requests with only one sample. Supported in Redoc CE.

htmlTemplate
string

Sets the path to the optional HTML file used to modify the layout of the reference docs page. Supported in Redoc CE.

jsonSampleExpandLevel
number >= 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 all that expands all levels. Supported in Redoc CE.

object

Largely deprecated, previously used to control the layout of API documentation when using pagination. Use the new 'pagination' option instead.

maxDisplayedEnumValues
number
Default: ""

Displays only the specified number of enum values. The remaining values are hidden in an expandable area. Supported in Redoc CE.

menuToggle
boolean
Default: true

If set to true, selecting the expanded menu item twice will collapse it. Supported in Redoc CE.

nativeScrollbars
boolean
Default: false

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. Supported in Redoc CE.

noAutoAuth
boolean
Default: false

Controls whether the Authentication section is inserted into the API documentation automatically. Supported in Redoc CE.

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.

onlyRequiredInSamples
boolean
Default: false

Shows only required fields in request samples. Supported in Redoc CE.

pagination
string
Default: "none"
Enum: "none" "section" "item"

Controls how the API documentation should be paginated. Supported values: 'none' (pagination disabled, all content is rendered on a single long page); 'section' (each tag with a set of associated operations is rendered as a separate page); 'item' (each tag and each operation are rendered on separate pages). The value of 'none' replaces deprecated 'layout.scope=all, routingStrategy=hash'. The value of 'section' replaces deprecated 'layout.scope=section, routingStrategy=browser'. The value of 'item' replaces deprecated 'layout.scope=item, routingStrategy=browser'.

pathInMiddlePanel
boolean
Default: false

Shows the path link and HTTP verb in the middle panel instead of the right panel. Supported in Redoc CE.

payloadSampleIdx
number >= 0
Default: 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. Supported in Redoc CE.

requiredPropsFirst
boolean
Default: false

Shows required properties in schemas first, ordered in the same order as in required array. Supported in Redoc CE.

routingBasePath
string
Default: ""

Specifies the base path when reference docs are hosted at something other than the root (/) of their domain.

routingStrategy
string
Deprecated

Deprecated configuration option.

scrollYOffset
string
Default: 0

If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc. Supported in Redoc CE. Note that you can specify the 'scrollYOffset' value in any of the following ways:

  • as a number - a fixed number of pixels to be used as the offset.
  • as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom will be used as the offset.
  • a function (advanced) - a getter function. Must return a number representing the offset (in pixels).
searchAutoExpand
boolean
Default: true

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.

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.

searchMode
string
Default: "default"
Enum: "default" "path-only"

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.

showConsole
boolean
Default: true

Enables or disables the API Console (the Try it functionality) in the right panel.

showExtensions
boolean
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 true, all specification extensions are shown. Supported in Redoc CE.

showRightPanelToggle
boolean

When set to 'true', displays a button that you can select to show or hide the entire right panel with code samples. This is an experimental option.

sideNavStyle
string
Default: "summary-only"
Enum: "summary-only" "path-first"

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.

simpleOneOfTypeLabel
boolean
Default: false

Shows only unique oneOf types in the label without titles. Supported in Redoc CE.

sortPropsAlphabetically
boolean
Default: false

Sorts properties in schemas alphabetically. Supported in Redoc CE.

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 charset=utf in mime-type.

untrustedSpec
boolean
Default: false

If set to true, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS. Supported in Redoc CE.

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",
    },
  },
}, document.querySelector('#redoc_container'))

Example .redocly.yaml configuration

The .redocly.yaml configuration is compatible with the CLI and our hosted API registry.

referenceDocs:
  licenseKey: <license-key-here>
  pagination: section
  showConsole: true
  theme:
    menu:
      backgroundColor: '#ffffff'