Skip to content
Get packs

Guide · Open source

How to use Redoc: generate API docs from an OpenAPI file

Updated · written with AI from the project's own documentation and checked against our catalogue data

Redoc is an open source tool that reads an API definition file and generates a documentation website from it. It supports OpenAPI (formerly Swagger), AsyncAPI and GraphQL. This guide shows you how to generate a static HTML file from the command line, embed Redoc in a plain HTML page, or use the React component, so you can publish API reference docs without writing them by hand.

RedocRedocly/redoc · ★ 26k · MIT

Quick start

  1. 1Prepare your spec. Have an OpenAPI, Swagger, AsyncAPI or GraphQL definition file ready, such as openapi.yaml.
  2. 2Install Node.js. Install Node.js so you can run npx and npm commands.
  3. 3Generate the HTML. Run npx @redocly/cli build-docs openapi.yaml in the folder with your spec.
  4. 4Open the output. Open the generated redoc-static.html file in your browser to check the docs.
  5. 5Embed in a page (optional). Add a redoc element with a spec-url attribute and the standalone script to an HTML page.
  6. 6Use React (optional). Import RedocStandalone from redoc and pass your spec URL as specUrl.

What you need before you start

Redoc renders an existing API definition; it does not write one. You need a file such as openapi.yaml that describes your API.

To use the command-line option, you need Node.js installed, since the install method uses npx and npm.

  • An API definition file (OpenAPI, Swagger, AsyncAPI or GraphQL)
  • Node.js for the npx and npm usage
  • An HTML page or React project if you want to embed Redoc instead

Generate static docs from the command line

If you have Node installed, you can generate documentation with npx. Run this in the folder containing your spec file.

By default the tool writes to a file named redoc-static.html. Open that file in your browser to see the result.

npx @redocly/cli build-docs openapi.yaml

Embed Redoc in an HTML page

Create an HTML page, or edit an existing one, and add the Redoc element and script inside the body tags. Set the spec-url attribute to the location of your definition.

Open the HTML file in your browser and your API documentation appears. The attribute can point to a local file, an AsyncAPI definition or a GraphQL schema. The library can also be installed locally with npm and served from your own server.

<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>

Use Redoc as a React component

If your app is built with React, import RedocStandalone from the redoc package and pass your spec URL as the specUrl prop.

import { RedocStandalone } from 'redoc'; <RedocStandalone specUrl="https://example.com/openapi.yaml" />;

Customise the output with extensions and configuration

Redoc is configurable, and it reads several OpenAPI specification extensions from your file. For example, x-logo sets an API logo, x-tagGroups groups tags in the side menu, and x-codeSamples adds operation code samples.

Dark mode and theming are available through CSS variables. The configuration documentation lists the full set of options.

  • x-logo: API logo
  • x-tagGroups: group tags in the side menu
  • x-displayName: human-friendly menu category names
  • x-codeSamples: operation code samples
  • x-summary: response button text

Know what the community edition does not include

Redoc Community Edition is the open source product. The README says the hosted Redoc product adds a try-it panel, a mock server, role-based access control, automated code samples, feedback widgets and linting, and that it supports SOAP.

If you need those features, the README points to Redocly's hosted offering instead of the open source package.

What people use it for

  • Publishing a public API reference from an existing OpenAPI file
  • Generating a static HTML file of API docs from the command line
  • Embedding API docs inside a React app or plain HTML page
  • Keeping docs in step with a spec file that changes over time
  • Showing AsyncAPI or GraphQL definitions as documentation

Frequently asked questions

Is Redoc free to use?

Redoc is an open source tool released under the MIT licence. The README describes the community edition as open source and points to Redocly's paid hosted product for extra features like the try-it panel and mock server.

What do I need to install Redoc?

The README lists Node.js as the prerequisite for npx and npm usage. You can run the generator with npx @redocly/cli build-docs openapi.yaml, or install the library with npm.

What file formats does Redoc support?

Redoc supports OpenAPI 3.2, 3.1, 3.0 and Swagger 2.0, as well as AsyncAPI 3.x and GraphQL (SDL). The format is detected from the document.

Does Redoc have a try-it panel?

The community edition does not list a try-it panel. The README says the try-it panel, mock server and access control are part of Redocly's hosted Redoc product.

Can Redoc create my API spec for me?

No. Redoc renders existing API definition files and does not write them, so you need an OpenAPI, Swagger, AsyncAPI or GraphQL file first.

How does Redoc compare to Swagger UI?

Redoc and Swagger UI are both listed as comparable projects in the source, along with Stoplight Elements and RapiDoc. The source does not include a direct feature comparison, so test each against your own spec before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Redoc suits teams that already maintain OpenAPI, Swagger, AsyncAPI or GraphQL files and want clean, generated API reference docs that they can host themselves. If you need a try-it panel, mock servers, access control or SOAP support, the README points to Redocly's hosted product, so consider that or a tool like Swagger UI instead.

Install options & downloads