This is the README for the 2.x
version of Redoc (React-based).
The README for the 1.x
version is on the v1.x branch
Live demo
Features
-
Command-line interface to bundle your docs into a zero-dependency HTML file
-
Responsive three-panel design with menu/scrolling synchronization
-
Deep linking support
-
Ability to integrate your API introduction into the side menu
-
High-level grouping in side-menu with
x-tagGroups
specification extension -
Branding/customizations using the
theme
option -
OpenAPI v3.0 support
-
Basic OpenAPI v3.1 support
-
Broad OpenAPI v2.0 feature support (yes, it supports even
discriminator
)
Releases
Important: all the 2.x releases are deployed to npm and can be used with jsdeliver:
- particular release, for example,
v2.0.0-alpha.15
: https://cdn.jsdelivr.net/npm/redoc@2.0.0-alpha.17/bundles/redoc.standalone.js next
release: https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js
Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN (deprecated):
- particular release, e.g.
v1.2.0
: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js v1.x.x
release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.jslatest
release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg.
Version Guidance
ReDoc Release | OpenAPI Specification |
---|---|
2.0.0-alpha.54 | 3.1, 3.0.x, 2.0 |
2.0.0-alpha.x | 3.0, 2.0 |
1.19.x | 2.0 |
1.18.x | 2.0 |
1.17.x | 2.0 |
Showcase
Deployment
For step-by-step instructions for how to get started using Redoc to render your OpenAPI definition, refer to the Redoc quickstart guide.
ReDoc CLI
For more information on Redoc's commmand-line interface, refer to Using the Redoc CLI.
Configuration
Security Definition location
You can inject the Security Definitions widget into any place in your definition description
.
For more information, refer to Security definitions injection.
OpenAPI specification extensions
Redoc uses the following specification extensions:
x-logo
- is used to specify API logox-traitTag
- useful for handling out common things like Pagination, Rate-Limits, etcx-codeSamples
- specify operation code samplesx-examples
- specify JSON example for requestsx-nullable
- mark schema param as a nullablex-displayName
- specify human-friendly names for the menu categoriesx-tagGroups
- group tags by categories in the side menux-servers
- ability to specify different servers for API (backported from OpenAPI 3.0)x-ignoredHeaderParameters
- ability to specify header parameter names to ignorex-additionalPropertiesName
- ability to supply a descriptive name for the additional property keysx-summary
- For Response object, use as the response button text, with description rendered under the buttonx-extendedDiscriminator
- In Schemas, uses this to solve name-clash issues with the standard discriminatorx-explicitMappingOnly
- In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object
<redoc>
options object
You can use all of the following options with the standalone version of the tag by kebab-casing them. For example, scrollYOffset
becomes scroll-y-offset
, and expandResponses
becomes expand-responses
.
disableSearch
- disable search indexing and search box.expandDefaultServerVariables
- enable expanding default server variables, defaultfalse
.expandResponses
- 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.maxDisplayedEnumValues
- display only specified number of enum values. hide rest values under spoiler.hideDownloadButton
- do not show "Download" spec button. THIS DOESN'T MAKE YOUR SPEC PRIVATE, it just hides the button.hideHostname
- if set, the protocol and hostname is not shown in the operation definition.hideLoading
- do not show loading animation. Useful for small docs.hideSchemaPattern
- if set, the pattern is not shown in the schema.hideSingleRequestSampleTab
- do not show the request sample tab for requests with only one sample.expandSingleSchemaField
- automatically expand single field in a schemajsonSampleExpandLevel
- set the default expand level for JSON payload samples (responses and request body). Special value"all"
expands all levels. The default value is2
.hideSchemaTitles
- do not display schematitle
next to to the typesimpleOneOfTypeLabel
- show only unique oneOf types in the label without titleslazyRendering
- Not implemented yetif set, enables lazy rendering mode in ReDoc. This mode is useful for APIs with big number of operations (e.g. > 50). In this mode ReDoc shows initial screen ASAP and then renders the rest operations asynchronously while showing progress bar on the top. Check out the demo for the example.menuToggle
- if true clicking second time on expanded menu item will collapse it, defaulttrue
.nativeScrollbars
- use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs).noAutoAuth
- do not inject Authentication section automatically.onlyRequiredInSamples
- shows only required fields in request samples.pathInMiddlePanel
- show path link and HTTP verb in the middle panel instead of the right one.requiredPropsFirst
- show required properties first ordered in the same order as inrequired
array.scrollYOffset
- 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.
- 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: A getter function. Must return a number representing the offset (in pixels).
showExtensions
- show vendor extensions ("x-" fields). Extensions used by ReDoc are ignored. Can be boolean or an array ofstring
with names of extensions to display.sortPropsAlphabetically
- sort properties alphabetically.payloadSampleIdx
- if set, payload sample will be inserted at this index or last. Indexes start from 0.theme
- ReDoc theme. For details check theme docs.untrustedSpec
- if set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS. Disabled by default for performance reasons. Enable this option if you work with untrusted user data!
<redoc>
theme object
spacing
unit
: 5 # main spacing unit used in autocomputed theme values latersectionHorizontal
: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8sectionVertical
: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
breakpoints
# breakpoints for switching three/two and mobile view layoutssmall
: '50rem'medium
: '85rem'large
: '105rem'
colors
tonalOffset
: 0.3 # default tonal offset used in computations
typography
fontSize
: '14px'lineHeight
: '1.5em'fontWeightRegular
: '400'fontWeightBold
: '600'fontWeightLight
: '300'fontFamily
: 'Roboto, sans-serif'smoothing
: 'antialiased'optimizeSpeed
: trueheadings
fontFamily
: 'Montserrat, sans-serif'fontWeight
: '400'lineHeight
: '1.6em'
code
# inline code stylingfontSize
: '13px'fontFamily
: 'Courier, monospace'lineHeight
: # COMPUTED: typography.lineHeightfontWeight
: # COMPUTED: typography.fontWeightRegularcolor
: '#e53935'backgroundColor
: 'rgba(38, 50, 56, 0.05)'wrap
: false # whether to break word for inline blocks (otherwise they can overflow)
links
color
: # COMPUTED: colors.primary.mainvisited
: # COMPUTED: typography.links.colorhover
: # COMPUTED: lighten(0.2 typography.links.color)
menu
width
: '260px'backgroundColor
: '#fafafa'textColor
: '#333333'activeTextColor
: # COMPUTED: theme.menu.textColor (if set by user) or theme.colors.primary.maingroupItems
# Group headingstextTransform
: 'uppercase'
level1Items
# Level 1 items like tags or section 1st level itemstextTransform
: 'none'
arrow
# menu arrowsize
: '1.5em'color
: # COMPUTED: theme.menu.textColor
logo
maxHeight
: # COMPUTED: menu.widthmaxWidth
: # COMPUTED: menu.widthgutter
: '2px' # logo image padding
rightPanel
backgroundColor
: '#263238'width
: '40%'textColor
: '#ffffff'
Development
see CONTRIBUTING.md