Redoc: OpenAPI Reference Documentation as a React Component

The problem Redoc solves, and who hits it

A hand-written API reference drifts from the spec the moment an endpoint changes. Redoc takes the machine-readable definition as the source and renders the page from it, so the page cannot disagree with the file it was built from.

The README states the tool generates documentation from OpenAPI (formerly Swagger) definitions, and that the default output is a three-panel responsive layout: a left panel with search and navigation, a central panel with the documentation, and a right panel with request and response examples. That layout is the product. Readers land on an operation, see its parameters and schemas, and see example payloads beside it without leaving the page.

The audience is API teams that already maintain an OpenAPI file. If your spec is generated by a framework, or written by hand and linted, Redoc is the last step in that pipeline. Teams that have no spec have nothing for Redoc to render, and no amount of configuration fixes that.

How the renderer turns a spec into three panels

Redoc is a TypeScript project, and package.json exposes it as a library rather than only a site generator. The main field points to bundles/redoc.lib.js, the browser field to bundles/redoc.browser.lib.js, and the types field to typings/index.d.ts. That layout explains the three delivery shapes the README lists: a CLI, an HTML tag, and a React component.

The repository ships webpack configurations for separate bundles. The scripts include bundle:standalone, bundle:lib and bundle:browser, and the README's HTML example loads redoc.standalone.js from the CDN. The standalone bundle is what makes the single-file deployment possible: the page needs no build step, only a script tag and a custom element.

The React path is different. The library bundle is imported into an application, and the component renders the reference inside your own routing and layout. The README notes simple integration with create-react-app. Both paths read the same definition and produce the same three-panel structure, so the choice is about where the page lives, not what it looks like.

Spec extensions are where Redoc diverges from a plain OpenAPI renderer. The README lists x-logo for the API logo, x-tagGroups for grouping tags in the side menu, x-codeSamples for operation code samples, x-badges, x-displayName for human-friendly menu names, and x-explicitMappingOnly for property lists on objects with additionalProperties. These are vendor extensions, so they are ignored by tools that do not know them. That is the trade-off: richer output in exchange for spec annotations that only Redoc reads.

Installing Redoc and rendering a first definition

The README gives a CLI path for a one-off build. With Node installed, npx runs the Redocly CLI and writes a static HTML file:

npx @redocly/cli build-docs openapi.yaml

The README states the tool outputs by default to redoc-static.html, which you can open in a browser. No server is involved at that point; the definition is baked into the page.

The second path needs no Node at all. Create an HTML file and put the element and script inside the body:

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>

Opening that file in a browser shows the API documentation on the page. The spec-url attribute is the part you change, and the README notes it can also point at a local file. Serving the library from your own server instead of the CDN is covered in the HTML deployment documentation.

For an application, install the package and import the component. The package.json main field is bundles/redoc.lib.js and the types field is typings/index.d.ts, so TypeScript consumers get declarations without a separate install.

npm install redoc

One detail worth checking before you build: the README's npm badge and the repository's package.json disagree on the current version, with package.json listing 2.5.4 while the newest release in the release list is v2.5.3. Pin an explicit version rather than a floating range, and read docs/config.md for the options that version supports.

Where Redoc stops: the hosted edition and the try-it console

The README is direct about the boundary. Under the heading Redoc vs hosted Redoc, it describes this project as Redocly's community-edition product and lists what the hosted product adds: a try-it console, automated code samples, fully custom styles, a mock server, AsyncAPI and GraphQL.

That list is the limitation. If your readers need to send a request from the reference page, the community edition is the wrong tool. The README does not document a built-in request console here; it names the try-it console as a hosted feature. The same applies to AsyncAPI and GraphQL: the README's opening describes Redoc as generating documentation from OpenAPI definitions, and the Redoc 3.0 announcement banner mentions one renderer for OpenAPI 3.2, AsyncAPI, GraphQL and MCP as something coming, not something shipped. Treat that banner as a roadmap statement, not a current capability.

Spec support is the other boundary. The README lists OpenAPI 3.1, OpenAPI 3.0 and Swagger 2.0. A definition in a format outside that set has no rendering path in this project.

There is also a maintenance question. The last push to the default branch was on 2026-09-16, and the most recent release in the list is v2.5.3 from 2026-05-29. The gap between releases is months, not days, which matters if you are waiting on a fix in a specific area. The repository is not archived, so the project is live, but the release cadence is not fast.

Redoc against Swagger UI and against hosted Redocly

The comparison readers search for most is Redoc versus Swagger UI. The README does not discuss Swagger UI, so the honest difference is the one Redoc's own documentation makes: Redoc renders a three-panel reading layout with request and response examples alongside the documentation, and it is consumed as a CLI, an HTML tag or a React component. Swagger UI is the other common renderer for the same OpenAPI input, and its emphasis is the interactive console. If your readers must try calls from the page, that emphasis is the deciding factor, and the README points you toward hosted Redoc instead.

The second comparison is Redoc versus Redocly, which the README answers directly. They are not two renderers of the same thing. Redoc is the community edition; Redocly's hosted product adds the try-it console, automated code samples, custom styles, a mock server, AsyncAPI and GraphQL. The difference is not visual quality. It is whether the page is a static artifact or a service.

A third option sits in the same repository family: the README points to Redocly CLI for linting and bundling in addition to docs. If your pipeline needs the spec validated before it is rendered, that is a separate tool from the renderer, and the README treats them as separate.

Licence, upgrades and the cost of staying current

Redoc is MIT licensed, both in the repository's LICENSE file and in the package.json license field. MIT permits commercial use and modification, and it requires the copyright notice and licence text to be preserved in distributions. That is a general description of the licence, not legal advice; if you vendor the bundle into a product, have your own counsel read the terms.

Upgrade cost is shaped by the release history. The listed releases are v2.5.0 in April 2025, v2.5.1 in September 2025, and v2.5.3 in May 2026. Patch and minor releases at that spacing mean a major-version jump is the event to plan for, not routine patches. The README's banner announces Redoc 3.0 as coming, describing a single renderer for OpenAPI 3.2, AsyncAPI, GraphQL and MCP. A 3.x line that changes the renderer's scope is the upgrade to watch, and the README does not document a migration path.

There is a second cost that is easy to miss: the vendor extensions. If your specs use x-tagGroups, x-codeSamples or x-logo, those annotations are part of your content, and any move to a renderer that ignores them loses that structure. The extensions are documented in the repository's docs folder, so the migration surface is at least enumerable.

Editorial conclusion

Adopt Redoc if you already have a valid OpenAPI definition and want a reference page that ships as one HTML file or one React component, with no server component. Do not adopt it if the reference page must let readers send live requests, since the README lists the try-it console among the features of hosted Redoc rather than this project. Before committing, render your own definition through the live demo at redocly.github.io/redoc, and check the docs/config.md options against the version of redoc you pin in package.json.

Frequently asked questions

Official sources

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