Add OpenAPI Docs to a Docusaurus Site

Docusaurus doesn’t ship a built-in way to render an OpenAPI spec — most projects either link out to a separately hosted viewer, or reach for a community plugin. If you’d rather keep the explorer on the same domain with zero extra dependencies, a custom page works, with one Docusaurus-specific wrinkle: pages are server-rendered at build time, and GetMan’s script needs a real browser to mount into.

Docusaurus’s own <BrowserOnly> component exists exactly for this — it skips server rendering for whatever you put inside it and only runs in the client.

Create the page

// src/pages/api-docs.tsx
import React, { useEffect, useRef } from 'react';
import Layout from '@theme/Layout';
import BrowserOnly from '@docusaurus/BrowserOnly';

function Explorer() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://cdn.getman.dev/latest/getman-ui.js';
    script.onload = () => {
      window.GetMan.launch(containerRef.current, {
        url: 'https://your-api.com/openapi.json',
      });
    };
    document.head.appendChild(script);
  }, []);

  return <div ref={containerRef} style={{ height: '100vh' }} />;
}

export default function ApiDocsPage() {
  return (
    <Layout title="API Docs">
      <BrowserOnly fallback={<div>Loading...</div>}>
        {() => <Explorer />}
      </BrowserOnly>
    </Layout>
  );
}

That’s a complete page at /api-docs on your Docusaurus site, using the same <Layout> component as your regular docs pages so the site header/footer stay consistent.

Linking it from the sidebar

src/pages/* files aren’t part of the docs sidebar automatically — add a manual link to it from docusaurus.config.js’s navbar items, or from a regular docs page, the same way you’d link to any other custom page.

Hosting the site (and the spec)

If you’re already hosting the Docusaurus site on GitHub Pages, see hosting docs on GitHub Pages for keeping the committed spec file in sync, or how to host an OpenAPI spec for free for other free options if it’s not.