New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →

redoc

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

redoc

Swagger-generated API Reference Documentation

0.6.1
Source
npm

Version published: 9 years ago

Weekly downloads: 409K; decreased by-21.66%

Maintainers: 1

Weekly downloads

Created: 9 years ago

What is redoc?

Redoc is an open-source tool for generating interactive API documentation from OpenAPI (formerly Swagger) definitions. It provides a user-friendly interface for exploring and understanding API endpoints, parameters, and responses.

What are redoc's main functionalities?

Render API Documentation

This feature allows you to render API documentation from an OpenAPI specification file. The `init` method takes the path to the OpenAPI file, optional configuration options, and the HTML element where the documentation should be rendered.

const Redoc = require('redoc');
Redoc.init('path/to/your/openapi.yaml', {
  scrollYOffset: 50
}, document.getElementById('redoc-container'));

Customization Options

Redoc allows for extensive customization of the rendered documentation. You can change the theme, colors, fonts, and other styles to match your branding.

const Redoc = require('redoc');
Redoc.init('path/to/your/openapi.yaml', {
  theme: {
    colors: {
      primary: {
        main: '#dd5522'
      }
    }
  }
}, document.getElementById('redoc-container'));

Standalone HTML Generation

Redoc provides a CLI tool to generate a standalone HTML file from an OpenAPI specification. This can be useful for hosting static API documentation without needing a server.

const { exec } = require('child_process');
exec('npx redoc-cli bundle path/to/your/openapi.yaml', (error, stdout, stderr) => {
  if (error) {
    console.error(`Error: ${error.message}`);
    return;
  }
  if (stderr) {
    console.error(`Stderr: ${stderr}`);
    return;
  }
  console.log(`Stdout: ${stdout}`);
});

Other packages similar to redoc

ReDoc

Swagger-generated API Reference Documentation

Live demo

Deployment

tl;dr

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <!-- needed for adaptive design -->
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!--
    ReDoc uses font options from the parent element
    So override default browser styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
        font-family: Verdana, Geneva, sans-serif;
        font-size: 14px;
        color: #333;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'>
    </redoc>
    <script src="bower_components/redoc/dist/redoc.min.js"> </script>
  </body>
</html>

1. Install redoc

Install using bower:

bower install redoc

or using npm:

npm install redoc --save

Alternatively you can just download redoc.min.js.

2. Reference redoc script in HTML

Then reference redoc.min.js in your HTML page:

<script src="bower_components/redoc/dist/redoc.min.js"> </script>

For npm:

<script src="node_modules/redoc/dist/redoc.min.js"> </script>

3. Add `<redoc>` element to your page

<redoc spec-url="<url to your spec>"></redoc>

4. Enjoy :smile:

Configuration

Swagger vendor extensions

ReDoc makes use of the following vendor extensions:

x-logo - is used to specify API logo
x-traitTag - useful for handling out common things like Pagination, Rate-Limits, etc
x-code-samples - specify operation code samples

Options

spec-url - relative or absolute url to your spec file
scroll-y-offset - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc. scroll-y-offset can be specified in various ways:
- number: A fixed number of pixels to be used as offset
- selector: selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom will be used as offset.
- function: A getter function. Must return a number representing the offset (in pixels).

Advanced usage

Instead of adding spec-url attribute to the <redoc> element you can initialize ReDoc via globally exposed Redoc object:

Redoc.init(specUrl, options)

options is javascript object with camel-cased version of options names as the keys. For example:

Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
  scrollYOffset: 50
})

Running locally

Clone repository git clone https://github.com/Rebilly/ReDoc.git
Go to the project folder cd ReDoc
Install node modules and front-end dependencies npm install npm run jspm-install
(optional) Replace demo/swagger.json with your own schema
Start the server npm start
Open http://localhost:9000

Keywords

FAQs

What is redoc?

Is redoc popular?

Is redoc well maintained?

Package last updated on 23 Feb 2016

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

redoc

What is redoc?

What are redoc's main functionalities?

Other packages similar to redoc

swagger-ui

api-docs

spectacle

ReDoc

Deployment

tl;dr

1. Install redoc

2. Reference redoc script in HTML

3. Add <redoc> element to your page

4. Enjoy :smile:

Configuration

Swagger vendor extensions

Options

Advanced usage

Running locally

Keywords

Related posts

Oracle Drags Its Feet in the JavaScript Trademark Dispute

Linux Foundation Warns Open Source Developers: Compliance with Sanctions Is Not Optional

Maven Central Adds Sigstore Signature Validation

3. Add `<redoc>` element to your page