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