Last updated 3 weeks ago

Configuration

To configure the Redocly API reference docs, specify the options in the second argument of the init function. You can use all the options available for ReDoc community-edition documented here.

Additionally, you can use the following options available only for Redocly API reference docs. We recommend utilizing a .redocly.yaml file when you use our Workflows/hosted service or our CLI for on-premise deployments.

Option Description
searchOperationTitleBoost Boost coefficient for search terms found in operation titles. The bigger value is, the higher searches will rank.
The default value is 4.
searchTagTitleBoost Boost coefficient for search terms found in operation titles.
The default value is 8.
searchFieldLevelBoost Boost coefficient for search terms found in field at specific level (if less than 1 searches found deeper would rank lower).
The default value is 0.95.
showConsole Enable the API Console (the Try it functionality).
hideLogo Hide the API logo.
layout The layout settings object.
layout.scope Controls the scope of the simultaneously rendered items.
Values:
  • all – render all the items.
  • section – render one section (top level heading) at the moment (default if layout.scope is "item").
  • item – render one item (operation) at the moment.
The default value is all.
layout.markdownItemsScope Controls the scope of the simultaneously rendered items populated from the markdown.
Values:
  • all– render all the items (default if layout.scope is "all" or "section")
  • section– render one section (top level heading) at the moment (default if layout.scope is "item").
The default value is all.
layout.showTag Indicate whether to show the tag on each endpoint page. Applicable only when layout.scope is "item".
The default value is true.
layout.showInfoOnEachPage Indicate whether to show the API info (version, title, download button) on each page. If set tofalse, it will be shown only on the first page.
The default value is false.
layout.showNextButton Indicate whether to show the "Next to ..." button at the end of each section.
The default value is true.
routingStrategy Routing strategy.
Values:
  • "hash" – URL-fragment based.
  • "browser"pushState/popState-based.
The default value is "hash".
routingBasePath The base path for the PushState-based routing strategy.
The default value is "".
sideNavStyle (default: "summary-only")
style of sidenav items.
Values:
  • "summary-only" – Show only summary in the sidenav.
  • "path-first" – Show the path first, and then show the summary below.
searchMode The search indexing mode.
Values:
  • "default" – the default mode.
  • "path-only" – the index and search only operation paths.
The default value is "default".
ctrlFHijack Control-F will bring focus to the search box.
The default value is false.
unstable_ignoreMimeParameters Apply workaround to ignore the charset=utf in mime-type.
The default value is false.
corsProxyUrl 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. Read more about the CORS proxy feature.
generateCodeSamples The object that controls the options for autogenerating code samples. See an example after this table.
Note that custom code samples directly added to the API definition using the x-codeSamples specification extension have precedence over auto-generated ones.
generateCodeSamples.languages Array of language config objects; indicates in which languages to generate code samples.
generateCodeSamples.languages.lang Can be one of curl, Node.js, JavaScript, Python, C#.
generateCodeSamples.languages.label Optional label for the generated code sample. Can be any string, e.g. JS or Awesome Language. When configured here, the label is displayed insted of lang as the tab caption in the Request samples section of your reference docs.
generateCodeSamples.skipOptionalParameters When enabled, optional parameters cookies, headers and query params are not included in generated code samples. The default value is false.
onlyRequiredInSamples Skip optional properties in auto-generated payload samples. It also affects generated code samples. The default value is false.
hideRequestPayloadSample Do not show request Payload example. The default value is false.

Example configuration with JavaScript library

RedoclyReferenceDocs.init('<path to api definition>', {
  licenseKey: '<license-key.here>',
  layout: {
    scope: '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>
  layout:
    scope: section
  routingStrategy: browser
  showConsole: true

Read more about configuration.