[opensourcedex]

redoc is a free, open source api development & testing project written in TypeScript and released under MIT. It has 25,913 GitHub stars, 2,395 forks and 449 open issues, and was last pushed 34 hours ago. On this registry it ranks #8 of 103 tracked projects in API Development & Testing, with 5 head-to-head comparisons available. It gained 5 stars over the last 3 tracked days.

What is redoc?

What it is

Redoc is an open-source tool for generating API reference documentation from OpenAPI definitions, formerly known as Swagger. It lives in the JavaScript and TypeScript ecosystem, ships under the MIT license, and is published on npm as the redoc package. By default it renders a responsive three-panel layout: a left panel holding the search bar and navigation menu, a central panel holding the documentation itself, and a right panel showing request and response examples.

The concrete problem it solves is turning a machine-readable OpenAPI definition into human-readable reference documentation without hand-writing pages. It supports OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0, so teams keep one specification as the source of truth and let Redoc render the docs from it. The project is the community edition of Redocly's product line, and the repository notes that Redoc 3.x is in development.

Key capabilities

  • Renders a responsive three-panel layout with menu and scrolling synchronized between panels.
  • Accepts OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0 definitions as input.
  • Supports grouping navigation entries at a high level through the x-tagGroups specification extension.
  • Integrates an API introduction into the side menu.
  • Displays code samples through a vendor extension.
  • Offers simple integration with create-react-app.
  • Distributes as a CLI tool, a Docker image, an HTML tag, and a React component.

Who uses it and how

  • Teams generate a standalone HTML file from a specification with the Redocly CLI and open the result in a browser.
  • Static sites embed the HTML tag with a spec-url attribute pointing at a hosted or local definition file.
  • React applications import Redoc as a component and render reference docs inside an existing front end.
  • The JavaScript library can be installed with npm and served from a team's own server for HTML deployment.
  • Organizations publish public API references with it; the README highlights Rebilly, Docker Engine, and Zuora.

Getting started

With Node installed, run npx @redocly/cli build-docs openapi.yaml, which writes redoc-static.html by default. Alternatively, add the Redoc HTML tag to a page with a spec-url attribute, install the library from npm, or use the Docker image; a hosted live demo at https://redocly.github.io/redoc/ renders a definition entered by URL.

When to use it — and when not to

Redoc covers OpenAPI reference rendering for free, while the hosted Redocly offering adds a try-it console, automated code samples, fully custom styles, a mock server, and AsyncAPI and GraphQL support. A self-hoster serves static HTML or a JavaScript bundle and therefore takes on that hosting themselves; the README does not describe a bundled database, storage layer, or SMTP service to operate. The evident limitation is that interactive request execution, style customization, and non-OpenAPI specification formats sit outside this community edition.

project readme (upstream, from github) — read inline

Learn what's coming in Redoc 3.x →

Generate beautiful API documentation from OpenAPI

npm License

bundle size npm jsDelivr status

About Redoc

Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions.

By default Redoc offers a three-panel, responsive layout:

  • The left panel contains a search bar and navigation menu.
  • The central panel contains the documentation.
  • The right panel contains request and response examples.

Redoc demo

Live demo

If you want to see how Redoc renders your OpenAPI definition, you can try it out online at https://redocly.github.io/redoc/.

A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your definition and select TRY IT.

Redoc features

  • Responsive three-panel design with menu/scrolling synchronization
  • Support for OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0
  • Ability to integrate your API introduction into the side menu
  • High-level grouping in side menu with the x-tagGroups specification extension
  • Simple integration with create-react-app
  • Code samples support (with vendor extension)
    code samples in action

Usage

Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component.

Generate documentation from the CLI

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

npx @redocly/cli build-docs openapi.yaml

The tool outputs by default to a file named redoc-static.html that you can open in your browser.

Redocly CLI does more than docs; check it out and add linting, bundling, and more to your API workflow.

Add an HTML element to the page

Create an HTML page, or edit an existing one, 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>

Open the HTML file in your browser, and your API documentation is shown on the page.

Add your own spec-url to the `` tag; this attribute can also be a local file. The JavaScript library can also be installed locally using npm and served from your own server, see the HTML deployment documentation for more details.

More usage options

Check out the deployment documentation for more options, and detailed documentation for each.

Redoc vs hosted Redoc

Redoc is Redocly's community-edition product. Looking for something more? We also offer a hosted Redoc with additional features including:

  • Try-it console
  • Automated code samples
  • Fully custom styles
  • Mock server
  • AsyncAPI
  • GraphQL

Documentation and resources

Showcase

A sample of the organizations using Redocly tools in the wild:

Pull requests to add your own API page to the list are welcome

Configuration

Redoc is highly configurable, see the configuration documentation for details.

OpenAPI specification extensions

Redoc uses the following specification extensions:

  • x-logo - is used to specify API logo
  • x-traitTag - useful for tags that refer to non-navigation properties like Pagination, Rate-Limits, etc
  • x-codeSamples - specify operation code samples
  • x-badges - specify operation badges
  • x-examples - specify JSON example for requests
  • x-nullable - mark schema param as a nullable
  • x-displayName - specify human-friendly names for the menu categories
  • x-tagGroups - group tags by categories in the side menu
  • x-servers - ability to specify different servers for API (backported from OpenAPI 3.0)
  • x-additionalPropertiesName - ability to supply a descriptive name for the additional property keys
  • x-summary - for Response object, use as the response button text, with description rendered under the button
  • x-explicitMappingOnly - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object

Releases

The README for the 1.x version is on the v1.x branch.

All the 2.x releases are deployed to npm and can be used with Redocly-cdn:

Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN (deprecated):

Development

see CONTRIBUTING.md

Frequently asked questions

Is redoc free to use?

redoc is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does redoc do?

📘 OpenAPI/Swagger-generated API Reference Documentation

What is redoc written in?

redoc is primarily written in TypeScript. Its source is publicly available at https://github.com/Redocly/redoc, and it has 25,913 GitHub stars.