Redocly/redoc redoc@3.0.0

on GitHub

Redoc 3.0 is a new renderer built on the same engine as Redocly's commercial API reference.
See What's new in Redoc 3 and the migration guide from 2.x.

Features

• ES module build. The package and the standalone bundle ship as ES modules.
  Load the bundle with <script type="module" src="…/bundles/redoc.standalone.js"> and import init (and hydrate for server-rendered markup) from it.
• Multiple specification types:
  One renderer for OpenAPI 3.2, 3.1 and 3.0, Swagger 2.0 (converted to OpenAPI 3 on load), AsyncAPI 3.x and 2.x, GraphQL SDL, and MCP servers described with x-mcp.
  The type is detected from the description.
  Format adapters load on demand.
• OpenAPI 3.2 support:
  additionalOperations, querystring parameters, itemSchema for streaming media types, and the tag summary, parent and kind fields for nested navigation.
• New design:
  Three-panel and stacked layouts (layout option), per-entity pages, deep links down to individual fields, and viewport-aware rendering for large descriptions.
• Hash and history routing:
  Every operation, schema and entity has its own route.
  • Hash routing (#/events/listspecialevents) is the default for the <redoc> element, the init function and the Docker image, and works on any static host.
  • History routing gives clean, shareable URLs such as /docs/events/listspecialevents. Enable it with router="history" and basePath.
    The server must return the page for every path under basePath.
  • The RedocStandalone React component uses history routing by default under basePath, or the host application's React Router when it renders inside one.
• Dark theme:
  Built-in light and dark color modes that follow the system preference, with a switcher in the sidebar.
• Customization with CSS variables:
  Override design tokens such as --color-primary-base or --sidebar-width in a stylesheet, scoped with :root.light and :root.dark.
• Search across operations, schemas, parameters and response codes, always enabled.
• Copy for LLM, Open in Claude and Open in ChatGPT actions in the page header.
• New options: router, basePath, events, codeSamples.languages, skipBundle, disableTelemetry, and AsyncAPI and GraphQL options such as jsonSamplesDepth, menu and info.
• Anonymous OpenTelemetry usage telemetry, on by default.

Breaking Changes

• The UMD bundle and the global Redoc object are removed.
  Redoc.init(spec, options, element, callback) becomes init(spec, options, element) imported from the bundle, without a callback.
• The theme option is removed with no compatibility shim.
  Use CSS variables instead.
• Requires Node.js 22 or later.
  Peer dependencies are now react and react-dom 18.3 or 19, react-router 7 or 8, styled-components 6 and @redocly/config.
  mobx and core-js are no longer needed.
• Deep links use the new route format, for example #/events/listspecialevents. 2.x links redirect on load, except links to schemas (#schema/<name>) and to single security schemes.
• Renamed options:
  • hideDownloadButton → hideDownloadButtons
  • jsonSampleExpandLevel → jsonSamplesExpandLevel
  • schemaExpansionLevel → schemasExpansionLevel
  • untrustedSpec → sanitize
  • generatedPayloadSamplesMaxDepth → generatedSamplesMaxDepth
  • requiredPropsFirst → sortRequiredPropsFirst (old name still accepted).
    downloadDefinitionUrl and downloadFileName are replaced by downloadUrls.
• Removed options:
  • allowedMdComponents
  • disableSearch
  • enumSkipQuotes
  • expandDefaultServerVariables
  • expandResponses
  • expandSingleSchemaField
  • hideFab
  • hideHostname
  • hideRequestPayloadSample
  • hideSecuritySection
  • hideSingleRequestSampleTab
  • labels
  • menuToggle
  • minCharacterLengthToInitSearch
  • nativeScrollbars
  • nonce
  • pathInMiddlePanel
  • payloadSampleIdx
  • showObjectSchemaExamples,
  • showSecuritySchemeType
  • showWebhookVerb
  • sideNavStyle
  • simpleOneOfTypeLabel
  • sortEnumValuesAlphabetically
  • sortOperationsAlphabetically
  • sortPropsAlphabetically
  • sortTagsAlphabetically
  • unstable_ignoreMimeParameters