Convert Figma logo to code with AI

Redocly logoredoc

📘 OpenAPI/Swagger-generated API Reference Documentation

23,260
2,283
23,260
353
View on GitHubView on NPM

Top Related Projects

swagger-api's avatar

swagger-ui

26,300

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

stoplightio's avatar

elements

1,712

Build beautiful, interactive API Docs with embeddable React or Web Components, powered by OpenAPI and Markdown.

Mermade's avatar

widdershins

1,479

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

OpenAPITools's avatar

openapi-generator

21,244

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

apiaryio's avatar

api-blueprint

8,642

API Blueprint

slatedocs's avatar

slate

36,008

Beautiful static documentation for your API

Quick Overview

Redocly/redoc is an open-source tool for generating interactive API documentation from OpenAPI (formerly Swagger) specifications. It provides a sleek, responsive, and customizable interface for developers to explore and understand APIs, making it easier to integrate and use them in their projects.

Pros

  • Automatically generates comprehensive API documentation from OpenAPI specs
  • Offers a modern, responsive design that works well on desktop and mobile devices
  • Supports theming and customization to match brand guidelines
  • Includes features like syntax highlighting, code samples, and interactive "Try it out" functionality

Cons

  • May require additional setup and configuration for complex API structures
  • Limited support for older OpenAPI/Swagger versions
  • Some advanced features may require a paid plan or self-hosting
  • Performance can be impacted with very large API specifications

Code Examples

  1. Basic usage with CDN:
<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='https://petstore.swagger.io/v2/swagger.json'></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
  </body>
</html>
  1. Customizing theme options:
<redoc
  spec-url="https://api.example.com/openapi.json"
  theme='{
    "colors": {
      "primary": {
        "main": "#32329f"
      }
    },
    "typography": {
      "fontSize": "16px",
      "fontFamily": "Arial, sans-serif"
    }
  }'
></redoc>
  1. Using ReDoc with React:
import { RedocStandalone } from 'redoc';

function ApiDocs() {
  return (
    <RedocStandalone
      specUrl="https://api.example.com/openapi.json"
      options={{
        nativeScrollbars: true,
        theme: { colors: { primary: { main: '#dd5522' } } },
      }}
    />
  );
}

Getting Started

To quickly get started with ReDoc:

  1. Install ReDoc:

    npm install redoc

  2. Create an HTML file with the following content:

    <!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <div id="redoc-container"></div>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
    <script>
      Redoc.init('https://petstore.swagger.io/v2/swagger.json', {}, document.getElementById('redoc-container'))
    </script>
  </body>
</html>

  3. Replace the spec URL with your own OpenAPI specification.

  4. Open the HTML file in a web browser to view your API documentation.

Competitor Comparisons

swagger-api logo

swagger-ui

26,300

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Pros of Swagger UI

  • More customizable with a wider range of configuration options
  • Better support for older OpenAPI/Swagger versions
  • Larger community and ecosystem, with more plugins and extensions available

Cons of Swagger UI

  • Heavier and slower to load, especially for large API specifications
  • Less modern and visually appealing default design
  • Requires more setup and configuration for optimal performance

Code Comparison

Swagger UI (basic setup):

import SwaggerUI from 'swagger-ui'
import 'swagger-ui/dist/swagger-ui.css'

SwaggerUI({
  dom_id: '#swagger-ui',
  url: 'https://petstore.swagger.io/v2/swagger.json'
})

ReDoc (basic setup):

import { RedocStandalone } from 'redoc'

<RedocStandalone
  specUrl="https://petstore.swagger.io/v2/swagger.json"
  options={{ scrollYOffset: 50 }}
/>

Both ReDoc and Swagger UI are popular tools for rendering OpenAPI/Swagger documentation. ReDoc offers a more modern, responsive design out of the box and generally performs better with large API specifications. However, Swagger UI provides more customization options and better support for older API specification versions. The choice between the two often depends on specific project requirements and personal preferences.

stoplightio logo

elements

1,712

Build beautiful, interactive API Docs with embeddable React or Web Components, powered by OpenAPI and Markdown.

Pros of Elements

  • More customizable and flexible, allowing for greater control over the API documentation layout
  • Supports multiple API specification formats, including OpenAPI 3.0, OpenAPI 2.0, and AsyncAPI
  • Offers a wider range of pre-built components for creating interactive API documentation

Cons of Elements

  • Steeper learning curve due to its more complex architecture and customization options
  • Requires more setup and configuration compared to Redoc's simpler implementation
  • May have a larger bundle size, potentially impacting page load times

Code Comparison

Elements:

import { API } from '@stoplight/elements';

<API
  apiDescriptionUrl="https://api.example.com/openapi.yaml"
  router="hash"
  layout="sidebar"
/>

Redoc:

import { RedocStandalone } from 'redoc';

<RedocStandalone
  specUrl="https://api.example.com/openapi.yaml"
  options={{ theme: { colors: { primary: { main: '#32329f' } } } }}
/>

Both libraries offer React components for embedding API documentation, but Elements provides more configuration options out of the box, while Redoc focuses on a simpler, more opinionated implementation.

Mermade logo

widdershins

1,479

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

Pros of Widdershins

  • Supports multiple output formats (Markdown, HTML, Slate)
  • Can generate documentation from various API description formats (OpenAPI, AsyncAPI, Semoasa)
  • Offers more customization options through templates and command-line arguments

Cons of Widdershins

  • Requires more setup and configuration compared to ReDoc's out-of-the-box solution
  • Less visually appealing default output, may require additional styling
  • Steeper learning curve for advanced customization

Code Comparison

Widdershins (Node.js usage):

const widdershins = require('widdershins');
const options = {};
widdershins.convert(apiDefinition, options, (err, output) => {
  // Handle output
});

ReDoc (HTML embedding):

<html>
  <head>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </head>
  <body>
    <redoc spec-url="path/to/api/definition.yaml"></redoc>
  </body>
</html>
OpenAPITools logo

openapi-generator

21,244

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

Pros of openapi-generator

  • Supports multiple programming languages and frameworks for code generation
  • Offers a wide range of customization options and templates
  • Can generate both client and server-side code

Cons of openapi-generator

  • Steeper learning curve due to its extensive features and options
  • May require additional configuration for complex API structures
  • Generated code might need manual refinement in some cases

Code comparison

redoc:

<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
<redoc spec-url="https://api.example.com/openapi.yaml"></redoc>

openapi-generator:

openapi-generator generate -i openapi.yaml -g java -o ./generated

Key differences

redoc focuses on API documentation rendering, providing a sleek and interactive interface for developers to explore APIs. It's primarily used for creating user-friendly API documentation websites.

openapi-generator, on the other hand, is a powerful tool for generating code across multiple languages and frameworks based on OpenAPI specifications. It's more suited for developers who need to create client libraries or server stubs for their APIs.

While redoc excels in documentation presentation, openapi-generator shines in code generation and automation of API-related development tasks.

apiaryio logo

api-blueprint

8,642

API Blueprint

Pros of API Blueprint

  • Language-agnostic design, allowing for broader adoption across different tech stacks
  • Simpler syntax, making it easier for non-technical stakeholders to read and contribute
  • Built-in support for mock servers and testing tools

Cons of API Blueprint

  • Less widespread adoption compared to OpenAPI (formerly Swagger)
  • Limited tooling ecosystem compared to ReDoc
  • Lacks some advanced features for complex API documentation

Code Comparison

API Blueprint:

# GET /message
+ Response 200 (text/plain)

        Hello World!

ReDoc (using OpenAPI):

/message:
  get:
    responses:
      '200':
        description: Successful response
        content:
          text/plain:
            example: Hello World!

While API Blueprint uses a more human-readable Markdown-like syntax, ReDoc utilizes the OpenAPI specification, which is more verbose but offers greater flexibility and tooling support. API Blueprint's simplicity makes it attractive for quick documentation, while ReDoc's OpenAPI base provides a more comprehensive solution for complex APIs and integrations.

slatedocs logo

slate

36,008

Beautiful static documentation for your API

Pros of Slate

  • More customizable and flexible, allowing for greater control over the documentation's appearance and structure
  • Supports multiple programming languages for code samples
  • Easier to integrate with existing static site generators or build processes

Cons of Slate

  • Requires more setup and configuration compared to Redoc's simpler implementation
  • May have a steeper learning curve for non-technical users
  • Less out-of-the-box support for OpenAPI/Swagger specifications

Code Comparison

Slate (Ruby):

require 'middleman'
require 'middleman-syntax'
require 'middleman-autoprefixer'
require 'middleman-sprockets'
require 'rouge'
require 'nokogiri'

Redoc (JavaScript):

import { RedocStandalone } from 'redoc';

<RedocStandalone
  specUrl="http://petstore.swagger.io/v2/swagger.json"
  options={{
    nativeScrollbars: true,
    theme: { colors: { primary: { main: '#dd5522' } } }
  }}
/>

Both Slate and Redoc are popular tools for creating API documentation, but they cater to different needs and preferences. Slate offers more customization options and flexibility, while Redoc provides a simpler, more streamlined approach with better support for OpenAPI/Swagger specifications out of the box. The choice between the two depends on the specific requirements of your project and the level of control you need over the documentation's appearance and functionality.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Redoc logo

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 <redoc> 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. Redocly API Reference

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

  • Try-it console
  • Automated code samples
  • Pagination
  • Extra theme options

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-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-ignoredHeaderParameters - ability to specify header parameter names to ignore
  • 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-extendedDiscriminator - in Schemas, uses this to solve name-clash issues with the standard discriminator
  • 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

NPM DownloadsLast 30 Days