Review of Redoc: Instant API Documentation

A major benefit of describing your API with a specification like the OpenAPI Specification (OAS) is that you can automatically generate documentation. There are plenty of tools for doing so — some open-source and others proprietary. Today, we’ll review an advanced solution called Redoc, evaluating its features and benefits, and comparing it to some popular alternatives.

What Is Redoc?

Redoc is an open-source tool that generates API documentation from OpenAPI specifications. It’s one of the most powerful free docs tools in the industry, producing clean, customizable documentation with an attractive three-panel design. With support for Markdown, it allows you to write and style descriptions with ease.

In practice, Redoc generates documentation by consuming an OpenAPI specification within the browser, eliminating the need for servers. However, there is also the option to serve static documentation by generating it in advance — we’ll touch on that later.

Redoc in practice with Rebilly. View the demo

Redoc vs Redocly

While Redoc itself is entirely open-source, its creators offer a managed documentation solution in the form Redocly. The service boasts improvements in speed and SEO-friendliness, lending thanks to a rewritten core. A free plan is available, but it requires $300 a month to get it white-labeled.

Features and Benefits

There are quite a few reasons why Redoc stands out among other documentation solutions. From attractive design to excellent compatibility and customizability, it’s no wonder this tool comes so highly recommended.

Excellent design

By default, Redoc uses a three-panel layout: the left panel features a search bar and navigation menu; the central panel contains the documentation itself, and the right panel houses request and response samples. This familiar and intuitive structure couldn’t be easier to consume, hence its use in highly-praised dev portals like those of Twilio and Stripe. With Redoc, it’s also responsive, automatically collapsing onto one or two panes on smaller screens.

Aside from the layout, there’s a lot to like about Redoc’s design. There’s plenty of whitespace on the page, and — although it’s all customizable — the default choice of fonts and colors is clean and appropriate.

Ease of installation

Installing Redoc couldn’t be easier — there are actually four different ways to deploy the tool. Perhaps the simplest of them is to paste some HTML onto a web page, which then loads some JavaScript on the client-side:



  
    ReDoc

You can host the JavaScript for Redoc yourself, or point to the public CDN (as above). Other than that, all you need to do is add the URL for your OpenAPI specification.

The other three installation options are:

As a React component
As a Docker image
As static HTML (generated with the CLI tool)

Customizability

Although documentation is limited, Redoc does offer some customization options. With the options object, you can add, remove, and tweak functional aspects of the documentation interface; for example:

hideDownloadButton removes the download button for your specification.
hideLoading removes the loading animation.
jsonSampleExpandLevel determines how many levels of a JSON payload will be displayed.

For purely visual changes — like fonts, colors, and spacing — you can either use Redoc’s theme option or add a link to some CSS in the <head> section of the HTML.

Extensive OAS support

Redoc prides itself on extensive support for the OpenAPI Specification. It goes beyond endpoint names, basic parameters, and response codes, and includes OpenAPI v3 properties.

“Redoc supports advanced OpenAPI v3 declarations like nested objects, the discriminator, “one of,” “any of,” “all of,” or nullable, and callbacks, which aren’t supported properly in competitor tools.”

Alternatives

There are dozens of documentation tools on the market, but Redoc stands out among them. In this section, we’ll look at how it compares to two popular open-source alternatives: Swagger UI and Slate.

Swagger UI

Swagger UI is probably the best-known solution for generating documentation from OpenAPI specifications. Selling points: it’s relatively easy to use and even boasts a “Try it now” button. However, our main critique is the design: it feels very outdated — and a little clumsy — when compared to Redoc.

See demo

Slate

Slate is another documentation generator that supports the popular three-panel design. Slate does a lot well: it’s flexible, it’s attractive, and it’s very SEO-friendly. With that, definitely keep it in mind as an alternative to Redoc.

See demo

Conclusion

If you’re looking for a tool that will generate beautiful documentation from an OpenAPI spec, Redoc is a formidable choice. Not only does it look great, but the open-source solution also is easy to implement, offers some customization, and supports both OAS2 and OAS3. As for alternatives, it’s definitely worth looking into Slate or Swagger UI.