Use the HTML element (self-hosted)

This page describes how to use the self-hosted Redocly API reference docs using the HTML element with the JavaScript snippet hosted on our CDN.

Prerequisites

You need to have a license key .
You need to have an OpenAPI definition and know the relative or absolute path to it. The path would be relative to the HTML page.

Steps

Add any HTML tag to the page that serves as a container for Redocly API reference docs .

Copy

Copied

<div id="redocly_container" />

Add the https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js script to the page.

Copy

Copied

<script src="https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js"></script>

Instead of using the latest version of the script, you can pin it to a specific version. We recommend version pinning for production deployments to prevent potential compatibility issues with the latest version. To pin the script, replace latest in the script URL with the exact tag of the version you're targeting. Version tags follow the vX.Y.Z format (for example: v1.4.0, v1.5.2...).

Copy

Copied

<script src="https://cdn.redoc.ly/reference-docs/v1.5.0/redocly-reference-docs.min.js"></script>

Host your copy of your OpenAPI files ( apiDefinition ), and be aware of how their path relates to the HTML page.

The path is used like this:

Copy

Copied

RedoclyReferenceDocs.init(
 'path/to/openapi.yaml',

Call function init on the globally exposed RedoclyReferenceDocs object with the following signature:

Copy

Copied

RedoclyReferenceDocs.init(
 apiDefinition: string | object,
 options: object = {},
 element: Element,
 callback?: () => void
)

The signature includes the following parameters:

apiDefinition – URL to the API definition or the API definition object itself.
options – the options object. For details, see Configuration . This must include your licenseKey as shown in the example below.
element – the HTML element of the container. By default, the <redoc> element is used.
callback – (optional) function that is called after rendering Redocly API reference docs .

Minimal setup

Copy

Copied

<!DOCTYPE html>
<html>
  <head>
    <title>Redocly API Reference Docs</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"
    />

    <!--
    Redocly doesn't change the outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <div id="redocly_container" />
    <script src="https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js"></script>
    <script>
      RedoclyReferenceDocs.init(
        '<url to the API definition>',
        { licenseKey: '<license-key.here>' },
        document.querySelector('#redocly_container'),
      );
    </script>
  </body>
</html>

Example with "Try It" console enabled

Copy

Copied

<!DOCTYPE html>
<html>
  <head>
    <title>Redocly API Reference Docs</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"
    />

    <!--
    Redocly doesn't change the outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <div id="redocly_container" />
    <script src="https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js"></script>
    <script>
      RedoclyReferenceDocs.init(
        '<url to the API definition>',
        { licenseKey: '<license-key.here>' },
        document.querySelector('#redocly_container'),
      );
    </script>
  </body>
</html>