Search results

Redoc Demo

Last updated: Sep 06, 2020

Redoc is a popular display framework for the OpenAPI as well and is a favorite by many API gurus. Redoc started out as a API doc site for Rebilly docs but with many customizations evolved into its own unique framework. Redoc provides a three-panel layout made popular by companies such as Stripe.

The makers of Redoc recently spun off into their own company (Redoc.ly) and are developing a more robust hosted solution offering (see From ReDoc to Redoc.ly). As with both Stoplight and Swagger, Redoc offers both free and pro versions to adjust to your needs. And you can add topics beyond just reference docs.

Redocly offers robust tools for authoring and publishing API docs using the command-line and docs-as-code workflows. For a fully tutorial, see Redocly tutorial – authoring and publishing API docs with Redocly’s command-line tools. The tutorial on that follows below is a simple way to use the community edition of Redoc.

Activity: Use Redoc to render OpenAPI spec

In this activity, you’ll render your OpenAPI spec with Redoc.

  1. Copy the following code into an empty text file (in a text editor such as Sublime Text) and save the file as redoc.html. (Note: This code comes from Redoc’s “TL;DR” readme instructions on GitHub.)

    <!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='https://stoplight.io/api/nodes.raw?srn=gh/tomjoht/stoplight_studio_weathermap/reference/openweathermap.v1.yaml'></redoc>
        <script src="https://cdn.jsdelivr.net/npm/[email protected]/bundles/redoc.standalone.js"> </script>
      </body>
    </html>
    

    Make sure you save the file with a .html extension so that your browser will render it as HTML.

  2. Change the value for redoc spec-url to a valid OpenAPI spec that is available at an online URL.

    If you were following the previous tutorial on creating an OpenAPI spec through Stoplight Studio (Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification document), you can use the OpenAPI URL that Stoplight provides. From your Stoplight Studio display, go to the Overview topic and click Export OpenAPI. Choose either original or dereferenced. Copy the URL. Here’s an example URL.

    Exporting an OpenAPI URL
    Exporting an OpenAPI URL
  3. In your web browser, click Cmd + O (Mac) or Ctrl + O (Windows), locate your redoc.html file, and select it.

    The display should look as follows:

    Sample Redoc display
    Sample Redoc display
Buy me a coffeeBuy me a coffee
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.)

67% Complete

67/159 pages complete. Only 92 more pages to go.