article thumbnail
OpenAPI Essentials
A comprehensive guide to understanding OpenAPI and why you need to use it.
#javascript, #html, #api

What is OpenAPI?

OpenAPI is a specification for describing REST APIs in a standardized, machine-readable format. Think of it as a blueprint that tells developers exactly how your API works - what endpoints exist, what data they expect, and what they return. OpenAPI specifications can be written in either JSON or YAML format. I personally prefer JSON over YAML but that is just me :) .

Instead of guessing how an API works or digging through outdated documentation, developers can read an OpenAPI spec (via UI tools like those explained below) and immediately understand everything they need to know.

Who Invented It and When?

In 2011 Tony Tam at Wordnik created "Swagger" to keep API documentation in sync with code. The name meant APIs should "swagger" with confidence. Then in 2015 SmartBear acquired Swagger and donated it to the Linux Foundation, renaming the spec to "OpenAPI" while keeping the Swagger tool brand. Today, The OpenAPI Initiative is backed by Google, Microsoft, IBM, and other major tech companies.

Who Uses OpenAPI?

There are many Major Companies that use OpenAPI including Google (Cloud APIs), Microsoft (Azure), GitHub, Stripe, Netflix, Twilio. It is used by major industries such as Financial services, healthcare, e-commerce, government agencies. In short, over 85% of Fortune 500 companies use OpenAPI in some form, with over 100,000 GitHub repositories containing OpenAPI specs.

Why You Need to Know It

If the fact that over 85% of the Fortune 500 companies use OpenAPI has not convinced you to learn it then here are a few more reasons:

  1. It's the industry standard - Most modern APIs use OpenAPI
  2. Career value - Essential skill for developers, DevOps, and technical writers
  3. Development efficiency - Auto-generate documentation, client SDKs, and tests
  4. Better teamwork - Specs serve as contracts between frontend/backend teams

OpenAPI JSON Document

An OpenAPI JSON document is a structured way to describe how an API works, so both humans and machines can understand it. At the top level, it includes basic metadata about the API (like title, version, and description in the info section), and a list of servers that specify the base URLs where the API is hosted. The main part is the paths section, which defines each endpoint (like /items) and the operations available on them (GET, POST, etc.). Each operation can include a summary, details about the request body if it accepts input, and responses that describe what it returns, often with JSON schemas to show the data structure. The example below shows the overall shape of an API without getting lost in too much detail.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API",
    "version": "1.0.0",
    "description": "A simple OpenAPI skeleton example"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/items": {
      "get": {
        "summary": "List items",
        "description": "Returns a list of items",
        "responses": {
          "200": {
            "description": "A list of items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create an item",
        "description": "Adds a new item",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": ["name"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Item created"
          }
        }
      }
    }
  }
}

The Five Essential OpenAPI UI Tools

In my research there are essentially five major players that use OpenAPI to generation API documentation. There are many more but I have found these five to be the most useful and easiest to impliment. Note: these are NOT in any order. Which you use is a user preference. However, of these five, ReDoc is the only one that does NOT have a "try it" feature. I personally love this feature so I always choose one of the other four on this list.

1 - RapiDoc

Found at https://rapidocweb.com/, RapiDoc is a lightweight web component for beautiful, interactive API docs. It has a small bundle size (~150KB) and is super customizable. One of my favorite features is the ability to specify the auth token right in the html. If a user is logged in already, I populate that field to make it super easy for them to use and try it out. Here is an example that I used in one of my recent projects.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>API Documentation</title>
  <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
  <style>
    html, body { height: 100%; margin: 0; }
    rapi-doc img { max-height: 100px; padding: 10px; }
  </style>
</head>
<body>
<rapi-doc id="rapidoc"
  spec-url="/path/to/openapi/json"
  heading-text="3PGL API Documentation"
  show-info="true"
  allow-try="true"
  allow-search="true"
  persist-auth="true"
  api-key-name="Authorization"
  api-key-location="header"
  api-key-value="Bearer {USER TOKEN HERE}"
  show-curl-before-try="true"
  >
</rapi-doc>
</body>
</html>

2 - Swagger

Found at https://swagger.io/docs/, Swagger is the original OpenAPI toolset with editor, UI, and code generation. Enterprises wanting a complete, commercially-supported ecosystem often turn to Swagger. Swagger also supports the "try it out" feature but it requires some javascript and finese to automatically authenticate a user. Here is a recent example of mine. Note that I also use javascript to set a custom logo that I specified in the OpenAPI JSON as x-logo.

<!DOCTYPE html> 
<html lang="en"> 
<head> 
  <meta charset="utf-8" /> 
  <meta name="viewport" content="width=device-width, initial-scale=1" /> 
  <meta name="description" content="API Documentation" /> 
  <title>API Documentation</title> 
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" /> 
  <style>
    #swagger-ui img {
      max-height: 100px;  /* control size */
      padding: 10px;     /* add padding */
    }
    </style>
</head> 
<body>
  <div id="swagger-ui"></div>
  <div style="display:none;" id="userauth">{USER AUTH KEY HERE}</div> 
  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script> 
  <script>
  window.onload = () => {
    // First fetch the spec JSON yourself
    fetch('/path/to/openapi/json')
      .then(res => res.json())
      .then(spec => {
        // Start Swagger UI
        window.ui = SwaggerUIBundle({
          spec: spec,       // use the loaded spec
          dom_id: '#swagger-ui',
        });

        // When UI is ready, check for x-logo
        setTimeout(() => {
          //set the authkey if given
          let ael=document.getElementById('userauth');
          if(ael.innerText.length){
            window.ui.preauthorizeApiKey("bearerAuth", ael.innerText);
          }
          const logoInfo = spec.info && spec.info['x-logo'];
          if (logoInfo && logoInfo.url) {
            const el = document.querySelector('div.info hgroup');
            if (el) {
              el.style.display = 'flex';
              el.style.alignItems = 'center';

              const logo = document.createElement('img');
              logo.src = logoInfo.url;
              logo.alt = logoInfo.altText || 'API Logo';
              logo.style.height = '60px';
              logo.style.marginRight = '12px';
              if (logoInfo.backgroundColor) {
                logo.style.backgroundColor = logoInfo.backgroundColor;
              }

              el.prepend(logo);
            }
          }
        }, 300);
      });
  };
</script>
</body> 
</html>

3 - Stoplight

Found at https://stoplight.io/, Stoplight is now owned by SmartBear. Developers often choose Stoplight over Swagger because it scales better for larger API ecosystems, supports versioning and governance, and integrates seamlessly into modern CI/CD pipelines. Like Swagger it also requires a bit of JavaScript finese to automatically assign an authorization key...the best way is to store it in local storage so that the application knows about it. Here is an example. 

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>API Documentation</title>
  <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
  <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
  <style>
    html, body { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="userauth" style="display:none;">{USER AUTH KEY HERE}</div>
  <script>
    (function () {
      const token = (document.getElementById('userauth')?.textContent || '').trim();
      if (!token) return;

      // use your OpenAPI security scheme id as the key (e.g., "bearerAuth")
      const schemeId = 'bearerAuth';

      const KEY = 'TryIt_securitySchemeValues';
      let store = {};
      try { store = JSON.parse(localStorage.getItem(KEY)) || {}; } catch (e) {}
      store[schemeId] = token;
      localStorage.setItem(KEY, JSON.stringify(store));
    })();
  </script>
  <elements-api
    apiDescriptionUrl="/path/to/openapi/json"
    router="hash"
    layout="sidebar">
  </elements-api>

</body>
</html>

4 - redoc

Found at https://github.com/Redocly/redoc, redoc is know as an open-source tool for generating responsive, beautiful API documentation. It also has excellent mobile support. redoc does not have "try it out" functionality so no need to auto assign an auth key. Here is an example using redoc:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>API Documentation</title>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
    <style>
    html, body, #redoc-container { height: 100%; margin: 0; }
    #redoc-container img {
      max-height: 100px;  /* control size */
      padding: 10px;     /* add padding */
    }
    </style>
  </head>
  <body data-onload="wacss.setActiveTab(document.getElementById('nav_redoc'));">
    <div id="redoc-container"></div>
    <script>
      Redoc.init('/path/to/openapi/json', {
        // optional: theme, hideDownloadButton: true, etc.
      }, document.getElementById('redoc-container'));
    </script>
  </body>
</html>

5 - OpenAPI Explorer (Authres)

Found at https://github.com/Authress-Engineering/openapi-explorer, Authress OpenAPI Explorer offers a lightweight, embeddable web component that's highly customizable and easy to drop into any app, making it more flexible for integration than heavier tools like Swagger UI or Stoplight. You can also use JavaScript to load your auth key for the "try it out" feature.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>API Documentation</title>
  <script type="module"
          src="https://unpkg.com/openapi-explorer@2.2.770/dist/browser/openapi-explorer.min.js">
  </script>
  <style>
    html, body { height: 100%; margin: 0; }
    openapi-explorer { height: 100%; display: block; }
  </style>
</head>
<body>
<openapi-explorer
  id="explorer"
  spec-url="/path/to/openapi/json"
  explorer-location="/path/to/openapi_explorer">
</openapi-explorer>

<div id="userauth" style="display:none;">{User Auth Key Here}</div>

<script type="module">
  // Run after the custom element is registered
  await customElements.whenDefined('openapi-explorer');

  const el = document.getElementById('explorer');
  const token = (document.getElementById('userauth')?.textContent || '').trim();

  function applyAuth() {
    if (!token) return;
    // Use your actual scheme id from components.securitySchemes (e.g., "bearerAuth")
    el.setAuthenticationConfiguration('bearerAuth', { token });
  }

  // Apply after the spec is loaded (recommended)...
  el.addEventListener('spec-loaded', applyAuth, { once: true });
  // ...and also try immediately in case it's already loaded
  applyAuth();
</script>
</body>
</html>

Summary

The beauty of OpenAPI is that once you have a specification, you can use it with any of these tools interchangeably. Your investment in learning OpenAPI pays dividends across the entire ecosystem. OpenAPI has transformed from a simple documentation tool into the backbone of modern API development. Whether you're building your first API or managing hundreds of microservices, understanding OpenAPI is essential for professional software development.

Getting Started

  1. Write a basic OpenAPI spec (JSON or YAML format)
  2. Choose a tool based on your needs
  3. Generate documentation from your spec
  4. Iterate - keep your spec updated as your API evolves

Interesting Trivia