Using the Redoc HTML element

TL;DR final code example

<!DOCTYPE html>
<html>
  <head>
    <title>Redoc</title>
    <!-- needed for adaptive design -->
    <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">

    <!--
    Redoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
  </body>
</html>
Running Redoc locally requires an HTTP server

Loading local OpenAPI definitions is impossible without running a web server because of issues with same-origin policy and other security reasons.

Running Redoc locally

If you want to view your Redoc output locally, you can simulate an HTTP server.

Using Redocly OpenAPI CLI

Redocly OpenAPI CLI is an open source command-line tool that includes a command for simulating an HTTP server to provide a preview of your OpenAPI definition locally.

If you have OpenAPI CLI installed, cd into your project directory and run the following command:

openapi preview-docs openapi.yaml

By default, without providing a port, the preview starts on port 8080, and can be accessed at http://localhost:8080. To exit the preview, use control+C.

Using Python

If you have Python 3 installed, cd into your project directory and run the following command:

python3 -m http.server

If you have Python 2 installed, cd into your project directory and run the following command:

python -m SimpleHTTPServer 8000

The output after entering the command provides the local URL where the preview can be accessed. To exit the preview, use control-C.

Using Node.js

If you have Node.js installed, install http-server using the following npm command:

npm install -g http-server

Then, cd into your project directory and run the following command:

http-server

The output after entering the command provides the local URL where the preview can be accessed. To exit the preview, use control-C.

Step 1 - Install Redoc

You can install Redoc using one of the following package managers:

Initialize your package manager

If you do not have a package.json file in your project directory, you need to add one by initializing npm or yarn in your project. Use the command npm init for npm, or yarn init for yarn. These initialization commands will lead you through the process of creating a package.json file in your project.

For more information, see Creating a package.json file in the npm documentation or Yarn init in the yarn documentation.

Install Redoc with yarn

After navigating to your project directory in your terminal, use the following command:

yarn add redoc

Install Redoc with npm

After navigating to your project directory in your terminal, use the following command:

npm i redoc

Step 2 - Reference the Redoc script

You can reference the Redoc script using either a link to the files hosted on a CDN or the files located in your node modules folder.

To reference the Redoc script with a CDN link:

<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>

To reference the Redoc script with a node modules link:

<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>

Step 3 - Add the element

You can add the element to your HTML page and reference your OpenAPI definition using the spec-url attribute, or you can initialize Redoc using a globally exposed Redoc object.

Using the spec-url attribute

To add the element with the spec-url attribute:

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

Examples

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>

You can also use a local file (JSON or YAML) in your project, for instance:

<redoc spec-url="dist.json"></redoc>

Using a Redoc object

To add the element with a globally exposed Redoc object:

Redoc.init(specOrSpecUrl, options, element, callback)
  • specOrSpecUrl: Either a JSON object with the OpenAPI definition or a URL to the definition in JSON or YAML format.
  • options: See options object reference.
  • element: DOM element Redoc will be inserted into.
  • callback(optional): Callback to be called after Redoc has been fully rendered. It is also called on errors with error as the first argument.

Examples

<script>
Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
  scrollYOffset: 50
}, document.getElementById('redoc-container'))
</script>

You can also use a local file (JSON or YAML) in your project, for instance:

<script>
Redoc.init('dist.yaml', {
  scrollYOffset: 50
}, document.getElementById('redoc-container'))
</script>