Redoc 3: one script tag for OpenAPI, AsyncAPI and GraphQL reference docs, minus a try-it console

A redoc tag and a module script are the whole embed

The lightest way to publish Redoc is two lines inside the body of any HTML page. The first is a custom element pointing at your definition; the second loads the standalone bundle from Redocly's CDN:

    <redoc spec-url="https://example.com/openapi.yaml"></redoc>
    <script type="module" src="https://cdn.redoc.ly/redoc/v3.x/bundles/redoc.standalone.js"> </script>

The spec-url attribute accepts an OpenAPI file, an AsyncAPI definition or a GraphQL schema. The browser must be able to fetch the definition: remote origins need suitable CORS headers, and a local file may need to be served over HTTP because browsers restrict file URLs. Note the script tag carries type="module": the standalone bundle loads as an ES module, so keep that attribute when you copy the snippet into a template.

The CDN path names v3.x rather than an exact version, so the page follows whatever Redocly publishes in that line. If you need a page that never changes under you, install the library with npm and serve the bundle from your own server, which the HTML deployment guide on redocly.com covers.

build-docs bakes everything into redoc-static.html

The second path skips the live script entirely. With Node installed, Redocly CLI turns a definition into one HTML file:

npx @redocly/cli build-docs openapi.yaml

The output goes to redoc-static.html by default, and you can open it directly in a browser or drop it on any static host. Redocly CLI is a separate project, also distributed as a Docker image, and it does more than docs: linting and bundling of API definitions live in the same tool.

The trade-off between the two paths is about when the spec is read. The script tag fetches spec-url every time a visitor loads the page, so a new definition can appear on a subsequent load, subject to browser or CDN caching; an unreachable URL prevents fetching an uncached definition. The static build captures the definition at build time, so the page keeps working if the spec URL disappears, but it goes stale until someone runs build-docs again. Teams that already have a CI step for their API definition can run build-docs there and treat the HTML as a build artifact.

The npm package is ESM, exports two paths, and declares Node 22

For applications that render docs inside their own React tree, Redoc exports a component:

import { RedocStandalone } from 'redoc';

<RedocStandalone specUrl="https://example.com/openapi.yaml" />;

The package.json for 3.0.1 sets "type": "module", with main, module, and types all pointing into bundles/: bundles/redoc.js and bundles/redoc.d.ts. The exports map opens only three entries: the root import, ./bundles/*, and ./package.json. A project that reached into other internal paths of the package will find those imports refused, because Node resolves the exports map strictly. Only bundles, LICENSE, and README.md are published.

The engines field asks for node >=22 and npm >=10.0.0. A toolchain below those versions is outside what the package declares support for. Teams pinned to an older Node line for other reasons have two options: stay on the script tag from the CDN, which needs no Node at all, or run build-docs through Redocly CLI's Docker image, keeping the Node requirement inside the container.

Format detection covers OpenAPI 3.2 through Swagger 2.0, AsyncAPI 3.x and GraphQL SDL

Redoc 3 reads OpenAPI 3.2, 3.1, and 3.0, plus Swagger 2.0, and adds AsyncAPI 3.x and GraphQL in SDL form. You do not tell it which format you are giving it; the format is detected from the document. That keeps one embed snippet or one build-docs command working across a mixed set of APIs, which matters for organizations publishing REST, event-driven, and GraphQL interfaces side by side.

The AsyncAPI support is named as 3.x. If your event definitions are still written against an earlier AsyncAPI major version, plan a conversion or a test render before promising readers a Redoc page for them. The same applies to GraphQL: the supported input is SDL, so a schema that only exists as an introspection result needs to be exported to SDL first.

The layout is the same for every format. The left panel holds the search bar and navigation menu, the center panel holds the documentation, and the right panel holds request and response examples. Menu and scroll position stay synchronized, the layout is responsive, and the built-in search has been improved.

Menu structure and samples come from x- extensions in your spec

Much of what a Redoc page looks like is controlled from inside the API definition through specification extensions, not from a Redoc config file. x-tagGroups groups tags into categories in the side menu. x-displayName gives menu categories human-friendly names. x-traitTag marks tags that describe cross-cutting properties such as pagination or rate limits rather than navigation entries. x-logo sets the API logo, and x-badges adds badges to operations.

For content, x-codeSamples attaches code samples to operations, x-examples supplies JSON request examples, x-enumDescriptions lists enum values with their descriptions, and x-nullable marks a schema parameter as nullable. x-servers lets you specify different servers. Version 3 adds x-mcp, which documents MCP (Model Context Protocol) servers along with their tools and capabilities.

The consequence is that your OpenAPI file accumulates Redocly-specific keys. That is harmless for validators that ignore unknown x- fields, but it means the information architecture of your docs lives in the spec, and the menu grouping and hand-written samples stay tied to these keys if you ever change renderers. Visual styling is separate: dark mode and theming run through CSS variables.

The community edition has no try-it panel and no generated samples

Redoc is Redocly's community edition, and the line between it and the hosted Redoc product is drawn clearly. The hosted product adds a try-it panel called Replay, automated code samples, a mock server, feedback widgets, role-based access control, full customization, linting, and support for further specifications such as SOAP.

Two of those gaps change what you can promise readers. Without a try-it panel, the community edition page is read-only: a developer cannot send a request from the docs and see a live response, so if that matters to your audience you need a separate tool for it. Without automated code samples, every sample in the right panel either comes from the request and response examples in the spec or from x-codeSamples blocks you write and maintain by hand. If your API has many operations and several client languages, that is real ongoing work.

Role-based access control is also absent from the community build. A static redoc-static.html or a script-tag page is visible to anyone who can reach the URL, so access control for internal API docs has to come from the web server or hosting layer in front of it.

Copy and Open in ChatGPT or Claude actions sit on every page

Version 3 puts three actions on every page: Copy, Open in ChatGPT, and Open in Claude. They exist so readers can take a section of the docs into an AI assistant and ask questions about it, which suits public APIs where developers already work that way.

For internal or partner-only APIs the same buttons deserve a look before launch. They make it one click for a reader to move documentation text into a third-party assistant. Whether that is acceptable depends on your policies, not on Redoc, and the configuration documentation at redocly.com/docs/redoc/v3.x/config is where to check which page features can be adjusted before you publish.

Other page-level options include integrating your API introduction into the side menu and a simple React integration path for embedding the reference inside an existing application shell.

3.0.0 and 3.0.1 landed on the same day, a day after rc.4

The 3.x line is new. [email protected] was tagged on October 13, 2026, [email protected] followed on October 14, and [email protected] came out the same afternoon. The last push to the main branch was on October 31, 2026, and the package version in package.json is 3.0.1. Documentation for this line lives under redocly.com/docs/redoc/v3.x.

A patch release within hours of a major one says the release is moving fast. For production docs, pin an exact version in package.json rather than a range, and test your definitions against it before upgrading, especially if you lean on extensions such as x-tagGroups or x-codeSamples to shape the page.

The repository is a TypeScript project built with Vite and tested with Vitest. The npm scripts include start, which runs vite, build, which runs type checks, the library build, the standalone build, and minification, and unit, which runs vitest. A demo/ directory and a playground/ directory sit alongside src/ and e2e/ for anyone who wants to modify the renderer rather than consume it.

Editorial conclusion

Redoc suits teams that want a read-only, three-panel reference page generated from an OpenAPI, AsyncAPI or GraphQL file, either as a static HTML build or a script tag, with no server of their own. It is the wrong pick if readers need to send live requests from the docs, need generated code samples, or need SOAP, since those sit in Redocly's hosted Redoc. Before adopting 3.x, confirm your toolchain meets Node 22 and npm 10, pin the bundle version you load, and check that your AsyncAPI documents are on 3.x.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Redocly/redoc on GitHub
5. Releases