Last updated 2 weeks ago

Reference docs section of the configuration file

This documentation covers the reference docs section of the configuration file.

There are two reference documentation products

  • Redoc community edition (free)
  • Redocly Reference docs (premium)

Redocly Reference docs has additional features and theming options, and includes all of the Redoc CE options.

The following example configuration file indicates which configuration options are for Redoc CE. The other options will not work in Redoc CE.

Feature options

# items with `#CE` are supported in the community edition of Redoc

referenceDocs:

  # search:

  disableSearch: false  # CE # disable search indexing and hide search box.
  searchOperationTitleBoost: 4 # Boost coefficient for search terms found in operation titles. The bigger value is,
                               # the higher searches will rank.
  searchTagTitleBoost: 8 # Boost coefficient for search terms found in operation titles.
  searchFieldLevelBoost: 0.95 # Boost coefficient for search terms found in field at specific level (if less than 1 searches found deeper would rank lower).
  searchMode: "default" # The search indexing mode. Can be also "path-only" – the index and search only operation paths.
  ctrlFHijack: false # Brings focus to the search bar when control-F is pushed.

  # expansions:

  expandDefaultServerVariables: false  # CE # enable expanding default server variables
  expandResponses: "200,201"  # CE # specify which responses to expand by default by response codes.
                              # Values should be passed as 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
  jsonSampleExpandLevel: 2  # CE # set the default expand level for JSON payload samples (responses and request body).
                          # Special value 'all' expands all levels

  # sort

  requiredPropsFirst: false # CE  # show required properties first ordered in the same order as in required array.
  sortPropsAlphabetically: false # CE  # sort properties alphabetically.
  payloadSampleIdx: 0 # CE   # if set, payload sample will be inserted at this index or last. Indexes start from 0.

  # Toggle visibility of UI elements

  hideInfoSection: false # Hides the entire info section of the API definition when true.
  hideDownloadButton: false  # CE # do not show "Download" spec button. THIS DOESN'T MAKE YOUR DEFINITION PRIVATE, it just hides the button.
  hideHostname: false  # CE # if set to true, the protocol and hostname is not shown in the operation definition.
  hideLoading: false  # CE # do not show loading animation. Does not apply to CLI or Workflows rendered docs
  hideSingleRequestSampleTab: false  # CE # do not show the request sample tab for requests with only one sample.
  hideRequestPayloadSample: false # CE # Do not show request payload examples.
  menuToggle: true  # CE # if true clicking second time on expanded menu item will collapse it.
  nativeScrollbars: false # use native scrollbar for sidemenu instead of perfect-scroll
                          # (scrolling performance optimization for big definitions).
  noAutoAuth: false  # CE # do not inject Authentication section automatically.
  onlyRequiredInSamples: false  # CE # shows only required fields in request samples.
  pathInMiddlePanel:  false  # CE # show path link and HTTP verb in the middle panel instead of the right one.
  scrollYOffset: 0 # CE  # 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;
                   # scrollYOffset can be specified in various ways:
                   #  - number: A fixed number of pixels to be used as offset.
                   #  - css selector: 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 offset.
                   #  - function (advanced): A getter function. Must return a number representing the offset (in pixels).

  showExtensions: false # CE  # show vendor extensions ("x-" fields). Extensions used by ReDoc are ignored.
                        # Can be boolean or an array of string with names of extensions to display.

  untrustedSpec: false # CE  # if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS
  htmlTemplate: "" # CE  # Path to the optional HTML file used to modify the layout of the reference docs page.

  # Premium Feature options

  showConsole: true # Enable the API Console (the Try it functionality).
  hideLogo: false # Hide API Logo from x-logo vendor extension
  layout:
    scope: section # Controls the scope of the simultaneously rendered items.
                   # - all – render all the items.
                   # - section – render one tag at the moment
                   # - item – render one item (operation) at the moment.
    markdownItemsScope: all # Controls the scope of the simultaneously rendered items populated from the markdown description
                            # 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").
    showTag: true # Indicate whether to show the tag description on each endpoint page. Applicable only when layout.scope is "item".
    showInfoOnEachPage: false # Indicate whether to show the API info (version, title, download button) on each page. If set to false, it will be shown only on the first page.
    showNextButton: true # Indicate whether to show the "Next to ..." button at the end of each section.
  routingStrategy: browser # Routing strategy. "hash" – URL-fragment based, "browser" – pushState/popState-based (must be used with layout scope section or item)
  routingBasePath: "" # The base path for the PushState-based routing strategy.
  sideNavStyle: "summary-only" # style of sidenav items. Can be also "path-first" – Show the path first, and then show the summary below.
  unstable_ignoreMimeParameters: false # Apply workaround to ignore the `charset=utf` in mime-type.
  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.
  generateCodeSamples:
    languages:  # Array of language config objects; indicates in which languages to generate code samples.
      - lang: "" # Can be one of the following supported languages: "curl", "Node.js", "JavaScript", "Python", "C#".
        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.
    skipOptionalParameters: false # When enabled, optional parameters cookies, headers and query params are not included in generated code samples.

Theming

referenceDocs:
# Theme options below designated with `#CE` are supported by Redoc Community Edition (CE).

  # Control style, color, font, sizes, and spacing.

  theme:
    spacing:
      unit: 5 # CE  # main spacing unit used in autocomputed theme values later
      sectionHorizontal: 40 # CE  # Horizontal section padding. COMPUTED: spacing.unit * 8
      sectionVertical: 40 # CE  # Horizontal section padding. COMPUTED: spacing.unit * 8
    breakpoints: # CE  # breakpoints for switching three/two and mobile view layouts
      small: '50rem'
      medium: '85rem'
      large: '105rem'
    colors:
      tonalOffset: 0.3 # CE  # default tonal offset used in computations
      primary:
        main: '#32329f' # default primary color (used for headings, links, etc)
        # variations of primary color (NOTE: these currently computed variations are reserved for future use)
        light: # COMPUTED: lighten(colors.tonalOffset colors.primary.main)
        dark: # COMPUTED: darken(colors.tonalOffset colors.primary.main)
        contrastText: # COMPUTED: readableColor(colors.primary.main)
      success:
        main: '#00aa13' # default success color, not used directly
        light: # COMPUTED: lighten(colors.tonalOffset colors.success.main) - background
        dark: # COMPUTED: darken(colors.tonalOffset colors.success.main)
        contrastText: # COMPUTED: readableColor(colors.success.main)
      warning: # default warning color, used for recursive label
        main: '#d4ad03'
        light: # COMPUTED: lighten(colors.tonalOffset colors.warning.main)
        dark:  # COMPUTED: darken(colors.tonalOffset colors.warning.main)
        contrastText: '#ffffff'
      error: # default error color, not used directly
        main: '#e53935'
        light: # COMPUTED: lighten(colors.tonalOffset colors.error.main)
        dark: # COMPUTED: darken(colors.tonalOffset colors.error.main)
        contrastText: # COMPUTED: readableColor(colors.error.main)
      text:
        primary: '#333333' # Primary text color
        secondary: # COMPUTED: lighten(colors.tonalOffset colors.text.primary) - lighter text color
      border:
        dark: 'rgba(0, 0, 0, 0.1)' # endpoints borders, security requirements borders
        light: '#ffffff' # looks like not used
      responses: # responses colors
        success:
          color: # COMPUTED: colors.success.main
          backgroundColor: # COMPUTED: transparentize(0.9 colors.success.main)
        error:
          color: # COMPUTED: colors.error.main
          backgroundColor: # COMPUTED: transparentize(0.9 colors.error.main)
        redirect:
          color: '#ffa500'
          backgroundColor: # COMPUTED: transparentize(0.9 colors.responses.redirect.color)
        info:
          color: '#87ceeb'
          backgroundColor: # COMPUTED: transparentize(0.9 colors.responses.info.color)
      http: # http badges in left nav and endpoint info colors
        get: '#6bbd5b'
        post: '#248fb2'
        put: '#9b708b'
        options: '#d3ca12'
        patch: '#e09d43'
        delete: '#e27a7a'
        basic: '#999'
        link: '#31bbb6'
        head: '#c167e4'
    schema:
      linesColor: # COMPUTED: lighten(theme.colors.tonalOffset, desaturate(theme.colors.tonalOffset, theme.colors.primary.main))
                  # Colors of level lines in schema view
      defaultDetailsWidth: '75%' # Default vidth of details part of field
      typeNameColor: # COMPUTED: theme.colors.text.secondary
      typeTitleColor: # COMPUTED: theme.schema.typeNameColor
      requireLabelColor: # COMPUTED: theme.colors.error.main
      labelsTextSize: '0.9em'
      nestingSpacing: '1em' # padding between nesting schema
      nestedBackground: '#fafafa' # background of nested schema
      arrow: # schema arrow styling
        size: '1.1em'
        color: # COMPUTED: theme.colors.text.secondary

      # !! Redocly API Reference Only !!
      constraints:
        # typography settings for constraints (< 1 char, [1, 100), nullable)
        # see headings below for possible settings
      examples:
        # typography settings for example values
        # see headings below for possible settings
    typography:
      fontSize: '14px' # CE
      lineHeight: '1.5em' # CE
      fontWeightRegular: '400' # CE
      fontWeightBold: '600' # CE
      fontWeightLight: '300' # CE
      fontFamily: 'Roboto, sans-serif' # CE
      smoothing: 'antialiased' # CE
      optimizeSpeed: true # CE
      headings:
        fontFamily: 'Montserrat, sans-serif' # CE
        fontWeight: '400' # CE
        lineHeight: '1.6em' # CE
      code: # inline code styling
        fontSize: '13px' # CE
        fontFamily: 'Courier, monospace' # CE
        lineHeight: # COMPUTED: typography.lineHeight # CE
        fontWeight: # COMPUTED: typography.fontWeightRegular # CE
        color: '#e53935' # CE
        backgroundColor: 'rgba(38, 50, 56, 0.05)' # CE
        wrap: false # whether to break word for inline blocks (otherwise they can overflow) # CE
      links:
        color: # COMPUTED: colors.primary.main # CE
        visited: # COMPUTED: typography.links.color # CE
        hover: # COMPUTED: lighten(0.2 typography.links.color) # CE

      # !! Redocly API Reference Only !!
      heading1: # typography settings only for heading 1 styles
        fontSize: # not set by default
        fontWeight: # not set by default
        fontFamily: # not set by default
        lineHeight: # not set by default
        color: # not set by default
        transform: # not set by default
      heading2: # typography settings only for heading 2 styles
        # same as for heading1
      heading3: # typography settings only for heading 3 styles
        # same as for other headings
      rightPanelHeading: # typography settings only for heading styles in right panel
        # same as for other headings
      fieldName: # typography settings for field names in schemas and parameters
        # same as for headings
      tokens: # configure colors of syntax highlighting different tokens
        boolean:
          color: firebrick
        # Available tokens(usually you don't need to ovveride all of them, just check which are used in actual html):
        # doctype, cdata, punctuation, property, tag, number, boolean, constant, symbol, selector,
        # attr-name, string, char, builtin, inserted, operator, entity, url, variable, atrule, attr-value,
        # keyword, regex, important, important, bold, italic, entity, deleted

        # also you can mix them with dot which will work only if the piece of text has both tokens:
        "property.string":
          color: green

    menu:
      width: '260px' # CE
      backgroundColor: '#fafafa' # CE
      textColor: '#333333' # CE
      activeTextColor: # COMPUTED: theme.menu.textColor (if set by user) or theme.colors.primary.main # CE
      groupItems: # Group headings # CE
        textTransform: 'uppercase' # CE
      level1Items: # Level 1 items like tags or section 1st level items # CE
        textTransform: 'none' # CE
      arrow: # menu arrow # CE
        size: '1.5em' # CE
        color: # COMPUTED: theme.menu.textColor # CE

      # !! Redocly API Reference Only !!
      breakPath: false # for sideNavStyle: summary-first, break path into multiple lines if it does not fit
    logo:
      maxHeight: # COMPUTED: menu.width # CE
      maxWidth: # COMPUTED: menu.width # CE
      gutter: '2px' # logo image padding # CE
    rightPanel:
      backgroundColor: '#263238' # CE
      width: '40%' # CE
      textColor: '#ffffff' # CE
    codeSample: # right panel code samples
      backgroundColor: # COMPUTED: => darken(0.1 rightPanel.backgroundColor) # CE
      borderRadius: 0 # border radius of MD code samples

    ## Redocly API Reference advanced theming
    overrides:
      DownloadButton:
        custom: 'color: red;' # custom CSS to apply to Download Button
      NextSectionButton:
        custom: 'color: red;' # custom CSS to apply to Next Section Button