Search results

Create a display using Redoc

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.

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 (Create a OpenAPI specification using a visual editor (Stoplight Studio)), 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
58% Complete

58/131 pages complete. Only 73 more pages to go.

Donate?

Want to buy me lunch? Click the Donate button below to donate any amount through Paypal. Or log an issue or submit a pull request in GitHub to improve this content.