Redoc: Generate Beautiful API Reference Documentation from OpenAPI

Introduction

Redoc is a powerful open-source tool designed for generating stunning and interactive API reference documentation directly from your OpenAPI (formerly Swagger) definitions. Developed by Redocly, it transforms complex API specifications into user-friendly, navigable documentation. It offers a responsive three-panel layout, providing a search bar, navigation menu, the main documentation content, and clear request/response examples. Redoc supports OpenAPI 3.1, 3.0, and Swagger 2.0, ensuring broad compatibility for various API projects.

Installation

Redoc provides flexible installation and usage options, including a command-line interface (CLI) tool, an HTML tag for direct embedding, and a React component.

Generate documentation from the CLI

If you have Node.js installed, you can quickly generate documentation using npx:

npx @redocly/cli build-docs openapi.yaml

This command will output an HTML file, typically named redoc-static.html, which you can open in your browser to view your API documentation.

Add an HTML element to the page

You can also embed Redoc directly into any HTML page. Create or edit an HTML file and add the following within the <body> tags:

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

Replace "http://petstore.swagger.io/v2/swagger.json" with the URL or local path to your OpenAPI definition. For more detailed deployment options, including local installation of the JavaScript library, refer to the official Redoc documentation.

Examples

Redoc's intuitive design is best experienced through its live demo.

Live Demo

You can try Redoc online at https://redocly.github.io/redoc/. The demo displays a version of the Swagger Petstore API by default. You can easily test it with your own OpenAPI definition by entering its URL and selecting "TRY IT".

Three-Panel Layout

By default, Redoc presents a highly functional three-panel, responsive layout:

Left Panel: Contains a search bar and a comprehensive navigation menu for your API endpoints.
Central Panel: Displays the detailed API documentation, including descriptions, parameters, and schemas.
Right Panel: Shows request and response examples, often with code samples, to help developers understand how to interact with your API.

Why Use Redoc

Redoc stands out as an excellent choice for API documentation due to several compelling features:

Beautiful and Responsive Design: Its default three-panel layout is not only aesthetically pleasing but also fully responsive, ensuring a great experience on any device.
Broad OpenAPI Support: It supports OpenAPI 3.1, 3.0, and Swagger 2.0, making it compatible with a wide range of existing API specifications.
Highly Configurable: Redoc is highly configurable, allowing you to customize its appearance and behavior through various options and OpenAPI specification extensions.
Easy Integration: Whether you prefer a CLI tool, embedding directly into HTML, or using it as a React component, Redoc offers straightforward integration paths.
Community and Enterprise Backing: As an open-source project maintained by Redocly, it benefits from active development and is used by many prominent organizations like Rebilly, Docker Engine, and Zuora.

Redoc: Generate Beautiful API Reference Documentation from OpenAPI

Summary

Repository Information

Topics

Use at your own risk