Using the Redoc HTML element

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:

Copy
Copied
yarn add redoc

Install Redoc with npm

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

Copy
Copied
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.

CDN link

To reference the Redoc script with a CDN link:

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

Node modules link

To reference the Redoc script with a node modules link:

Copy
Copied
<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:

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

Examples

Copy
Copied
<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:

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

Using a Redoc object

To add the element with a globally exposed Redoc object:

Copy
Copied
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

Copy
Copied
<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:

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