Using Redoc to Auto-Generate OpenAPI Documentation

Developing an API is one task, but documentation is another huge effort in itself. It takes a lot of time to craft documentation that is easy to understand and implement. Thankfully, standards like OpenAPI Specification make it possible to ease the API documentation creation process.

In this tutorial, we’ll cover how to automatically generate API documentation from an OpenAPI definition. For this, we’ll be using Redoc, the free, open-source API documentation tool from Redocly. We’ll showcase how to generate stunning API documentation with OpenAPI and detail how to customize the look and feel of your documentation.

Features of OpenAPI Specification

First off, what is OpenAPI? OpenAPI Specification (OAS), formerly known as Swagger, is a standard open-source specification for describing REST APIs. For clients and servers that use REST APIs to interact, an OpenAPI Specification serves as a contract, laying out the API’s methods and documentation.

OpenAPI is language-agnostic, enabling developers to understand and use services without knowing how the server works or accessing the server code. It can assist in creating visually appealing and engaging API documentation and technical content deliverables that explain how the API operates.

Moreover, OpenAPI enables you to evaluate every component of your framework as it moves through the API design workflow. This is possible because OpenAPI definitions are machine-readable and can be used to assess the consistency of an API. OpenAPI has a wide userbase supported by many popular organizations such as Google, IBM, eBay, Microsoft, and much more. Due to the widespread adoption of the OpenAPI Specification, an extensive tooling ecosystem has developed.

Why Redoc.ly?

As we’ve covered previously, Redoc is an open-source documentation generator for OpenAPI specifications. The tool is highly customizable and comes with free as well as paid plans. The documentation generator is based on React JS and is responsive. Some features include:

Easy to use
Support for command-line integrations adds features for advanced users
Responsive three-panel design that accommodates much information on a single page
Support for multiple languages, including PHP, CURL, Node.JS, and Python
Backward compatibility for Open API Spec, supporting OpenAPI v2 and OpenAPI v3

Prerequisites

Now, let’s move ahead with generating some API documentation. For this tutorial, you will need:

Knowledge of HTML, JS, CSS
OpenAPI Specification file hosted on a public URL

Step 1: Upload your OpenAPI Specification file to a publicly accessible URL like Git

For this tutorial, we’ll be using this Git URL. The advantage of using Git is that it lets you generate a public URL that anyone can share and use.

You can write your OpenAPI Specification and upload it on git and make sure to copy the public URL.

Step 2: Creating the UI of the documentation

Now create a file called test.html and open it on your favorite code editor. After that, paste the below code:

<!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='YOUR_PUBLIC_URL_HERE'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
  </body>
</html>

Note: Replace YOUR_PUBLIC_URL_HERE with your public URL, not the secret one.

Code Explanation

We’re using the CDN method here, so you don’t have to worry about the dependency part. We’re also using Google Fonts CDN, which will help us add stylings to our documentation. You can use any other font that you want, but for now, we’re using the Montserrat font.

After loading all the stylings and our OpenAPI Specification, at the end, we’re calling the Redoc CDN to do the magic:

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

Step 3: Testing the documentation

Now, open the test.html in your browser, and you should see something like this:

That’s it! You have finally generated your API documentation using Redoc!

Step 4: Adding a custom logo

Most API documentation belongs to a specific company, right? And the company has a unique logo to identify it. So let’s try to add a logo to our documentation. To do so, update your YAML file and then add the below lines under the info section:

x-logo:
    url: "https://raw.githubusercontent.com/vyomsrivastava/redoc-ly/main/logo.png"
    backgroundColor: "#FFFFFF"
    altText: "Petstore logo"

Code Explanation:

The x-logo is an info object which takes parameters like url, backgroundColor, and altText for the styling. So you just need to upload the logo and pass it in the parameters.

Hosting the Documentation

Hosting the Redoc documentation is very easy since they’re static files. So, you can use any web host. You just need to upload the index.html file, which has the script to call the redoc scripts. You can put the YAML file on a Git public URL or simply place it on a webserver and pass the URL in the HTML file.

Scaling the Documentation

OpenAPI specification, which is on version 3.1.0 at the time of writing, specifies a standard, programming language-independent interface definition for RESTful APIs. Instead of XML components, OpenAPI uses a collection of JSON objects, each with its schema that specifies its naming, order, and contents. Anything within the ‘schema’ keyword in OpenAPI is described by the Schema Object.

One of the best features of this documentation generator is scalability. You can easily add new API endpoints by just updating the YAML or JSON without making any changes in the HTML file. Hence, this makes Redoc one of the best documentation generators.

Final Words

Documentation is a crucial step in the API development process. The use of OpenAPI specification provides various benefits to API developers as well as client businesses. It provides developers with a reference point for designing collaborative, innovative, and testable APIs that enhance their experience and enables them to provide top-of-the-range API products to end-users.

Not only this, but with the help of OpenAPI specification, you can save time and avoid mistakes while writing code. It can be converted into code using standard or modified toolchains, resulting in saving time and effort.

Redoc allows you to generate documentation using OpenAPI Specification very quickly and automatically. It also lets you integrate your CSS and styling so that it can match your product. Of course, Redoc is only one option. We have covered other documentation generators in this article.