Skip to main content

Building API Documentation with Docusaurus

· 5 min read
Building API Documentation with Docusaurus

Introduction​

Technical documentation is more than just a README - it’s a product in itself. For APIs, a clear and interactive documentation experience can make or break adoption.

In my previous article, I walked through setting up Docusaurus with Tailwind CSS and shadcn/ui components. In this post, we’ll take the next step: turning Docusaurus into a full-fledged API documentation platform powered by an OpenAPI specification.

Why use OpenAPI with Docusaurus?​

The OpenAPI Specification has become the industry standard for describing REST APIs. Instead of manually writing documentation, you define your API in a structured YAML or JSON file.

By integrating OpenAPI into Docusaurus, you get:

  • Single source of truth → Docs generated directly from your API spec.
  • Interactive explorers → Try out endpoints from the documentation.
  • Consistency → Updates to the OpenAPI file automatically reflect in your docs.

Preparing an OpenAPI File​

Let’s create a simple OpenAPI 3.0 file that describes an endpoint for a user list. Later, we’ll reference this file inside our Docusaurus project.

openapi.yaml
openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique user `id`
          readOnly: true
        username:
          type: string
          description: "[URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)
            compliant username in ASCII format. Allowed characters are lower case (a-z),
            upper case (A-Z), digits (0-9), hyphens (-), dots (.) and underscore (_).
            The username must be unique regardless of upper and lower case."
          maxLength: 60
        firstname:
          type: string
          description: First name of the user
          maxLength: 100
        lastname:
          type: string
          description: Last name of the user
          maxLength: 100
        email:
          type: string
          format: email
          description: Email address of the user
        emailVerified:
          type: boolean
          description: Flag to check if the user has verified his email address
          default: false
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: UTC timestamp the user was created - [ISO
            8601](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: UTC timestamp the user record was updated the last time - [ISO
            8601](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
      example:
        id: 100001
        username: jd
        firstname: John
        lastname: Doe
        email: john.doe@mail.com
        emailVerified: true
        createdAt: 2025-07-09T17:14:53+00:00
        updatedAt: 2025-07-10T11:25:40+00:00
    UserList:
      type: object
      properties:
        totalItems:
          type: integer
          readOnly: true
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
          readOnly: true

Integrating OpenAPI into Docusaurus​

Step 1: Install a Plugin​

One of the most popular approaches is using the Docusaurus plugin docusaurus-plugin-openapi-docs. This plugin automatically generates API reference docs from OpenAPI files. Let's install it:

npm install docusaurus-plugin-openapi-docs url
warning

This plugin still requires React 18.0.0, so we first need to downgrade our Docusaurus installation if you followed the previous tutorial:

npm install react@18.0.0 react-dom@18.0.0

There is an open pull-request on GitHub: https://github.com/cloud-annotations/docusaurus-openapi/pull/298

Step 2: Configure in docusaurus.config.js​

Add the preset and point it to your OpenAPI file:

import type * as Preset from 'docusaurus-preset-openapi';

const config: Config = {
  presets: [
    [
      "docusaurus-preset-openapi",
      {
        api: {
          path: "openapi.yaml",
          routeBasePath: "/api",
        },
      } satisfies Preset.Options,
    ],
  ],
}

This will generate docs from openapi.yaml and place them under /api.

For easier navigation, let’s also add a navbar item to access the API docs.

docusaurus.config.js
export default {
  themeConfig:
  ({
    navbar: {
      items: [
        {
          to: '/api',
          label: 'API',
          position: 'left'
        },
        ...
      ],
    },
http://localhost:3000/api
info

There is also an alternative plugin called redocusaurus available, which uses Redoc to render the OpenAPI spec.

Customizing the API Docs​

Because we’re using the Tailwind + shadcn/ui setup from the previous article, the generated docs can inherit the design system.

We can further enhance the API docs by:

  • Grouping endpoints by tag → for better navigation.
  • Adding Markdown pages alongside auto-generated docs for tutorials, guides, or conceptual overviews.
  • Styling components with Tailwind utilities for a consistent look and feel.

Adding an Interactive API Explorer​

If you want developers to try out endpoints directly from the documentation, you can integrate Swagger UI or Redoc.

For example, embedding Redoc:

npm install redoc

Then create a React component:

src/components/RedocApi.js
import React from 'react';
import { RedocStandalone } from 'redoc';

export default function RedocApi() {
  return (
    <RedocStandalone
      specUrl="/openapi.yaml"
      options={{ scrollYOffset: 60 }}
    />
  );
}

Now you can include <RedocApi /> in a Docusaurus page:

src/pages/redoc.js
import React from 'react'
import Layout from '@theme/Layout'
import RedocApi from '@/components/RedocApi'

export default function Redoc() {
    return (
        <Layout title="Redoc" description="Redoc page">
            <RedocApi/>
        </Layout>
    )
}

Add a navbar item to access the Redoc page:

docusaurus.config.js
export default {
  themeConfig:
  ({
    navbar: {
      items: [
        {
          to: '/redoc',
          label: 'Redoc',
          position: 'left'
        },
        ...
      ],
    },
http://localhost:3000/redoc

Putting It All Together​

At this point, your Docusaurus site provides:

  • A developer portal with guides and conceptual docs.
  • Auto-generated API docs synced with your OpenAPI spec.
  • An interactive explorer for testing endpoints.

This setup turns Docusaurus into a true API documentation platform, with customization power that few dedicated tools offer.

Conclusion​

By combining Docusaurus with OpenAPI, you can transform a static site into a robust developer hub. No more duplicated documentation, no more stale examples—just a single, maintainable source of truth.

If you’ve already followed the setup with Tailwind CSS and shadcn/ui, adding API docs is the logical next step. The result: a professional, modern, and developer-friendly documentation experience.