Skip to main content

OpenAPI Documentation Implementation

This document describes how we implemented professional, interactive API documentation for the DAGGH platform using docusaurus-openapi-docs.

🎯 Overview​

We successfully implemented a two-repository workflow where:

  • DAGGH repo: Contains the actual API routes and generates OpenAPI specifications
  • Docs repo: Contains Docusaurus site with auto-generated, interactive API documentation

🏗️ Architecture​

graph LR
    A[DAGGH API Routes] --> B[OpenAPI Generator]
    B --> C[daggh-api.yaml]
    C --> D[Copy Script]
    D --> E[Docs Repo Static Assets]
    E --> F[docusaurus-openapi-docs Plugin]
    F --> G[Generated MDX Files]
    G --> H[Beautiful Swagger UI]

✅ What We Achieved​

Interactive Features​

  • ✨ Beautiful Swagger UI with professional styling
  • ✨ Interactive "Try it out" functionality
  • ✨ Real-time parameter inputs
  • ✨ Live API testing directly in docs
  • ✨ Response examples and schema validation
  • ✨ Authentication support with JWT tokens

Developer Experience​

  • 🚀 Single command to update all API docs
  • 🔄 Automatic MDX generation from OpenAPI spec
  • 📱 Mobile-responsive design
  • 🎨 Consistent theming with Docusaurus
  • 📊 Organized sidebar with proper grouping

🛠️ Implementation Steps​

Phase 1: Package Installation (Docs Repo)​

cd docs/my-docs
pnpm add docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs @docusaurus/theme-common

Phase 2: Configuration (Docs Repo)​

docusaurus.config.ts:

export default {
  // ... existing config

  presets: [
    [
      "classic",
      {
        docs: {
          sidebarPath: "./sidebars.ts",
          docItemComponent: "@theme/ApiItem", // Key for OpenAPI theming
        },
        // ... other preset options
      },
    ],
  ],

  plugins: [
    [
      "docusaurus-plugin-openapi-docs",
      {
        id: "daggh-api",
        docsPluginId: "classic",
        config: {
          daggh: {
            specPath: "static/openapi/daggh-api.yaml",
            outputDir: "docs/api",
            sidebarOptions: {
              groupPathsBy: "tag",
              categoryLinkSource: "tag",
            },
            hideSendButton: false,
            showSchemas: true,
          },
        },
      },
    ],
  ],

  themes: ["docusaurus-theme-openapi-docs"],

  // ... rest of config
}

Updated Scripts:

{
  "scripts": {
    "gen-api-docs": "docusaurus gen-api-docs all",
    "clean-api-docs": "docusaurus clean-api-docs all",
    "refresh-api-docs": "pnpm run clean-api-docs && pnpm run gen-api-docs"
  }
}

Phase 3: Copy Automation (DAGGH Repo)​

openapi/copy-to-docs.js:

import fs from "fs"
import path from "path"

const DOCS_REPO_PATH = "../../docs/my-docs"
const SOURCE_SPEC = "./daggh-api.yaml"
const TARGET_SPEC = `${DOCS_REPO_PATH}/static/openapi/daggh-api.yaml`

try {
  // Ensure target directory exists
  const targetDir = path.dirname(TARGET_SPEC)
  if (!fs.existsSync(targetDir)) {
    fs.mkdirSync(targetDir, { recursive: true })
  }

  // Copy the generated spec to docs repo
  fs.copyFileSync(SOURCE_SPEC, TARGET_SPEC)
  console.log("✅ OpenAPI spec copied to docs repo")
} catch (error) {
  console.error("❌ Error copying OpenAPI spec:", error.message)
  process.exit(1)
}

Updated Scripts (DAGGH):

{
  "scripts": {
    "generate:openapi": "node generate-schema.js",
    "copy:docs": "node copy-to-docs.js",
    "docs:update": "npm run generate:openapi && npm run copy:docs",
    "docs:full": "npm run docs:update && cd ../../docs/my-docs && pnpm run refresh-api-docs"
  }
}

Phase 4: Sidebar Integration​

sidebars.ts:

import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"
import apiSidebar from "./docs/api/sidebar"

const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    // ... existing sections
    {
      type: "category",
      label: "API Documentation",
      collapsed: false,
      items: [
        "api/overview",
        ...apiSidebar, // Auto-generated API endpoints
      ],
    },
  ],
}

export default sidebars

🔄 Current Workflow​

For API Changes:​

# From DAGGH repo root
npm run docs:full

# This automatically:
# 1. Generates OpenAPI spec from route files
# 2. Copies spec to docs repo
# 3. Regenerates all API documentation
# 4. Ready to view at localhost:3000

For Documentation Updates:​

# From docs repo
cd docs/my-docs
pnpm start  # View changes locally
pnpm build  # Test production build

📁 File Structure​

Projects/
├── daggh/                           # API Implementation
│   ├── src/app/api/                # Route files (source of truth)
│   ├── openapi/
│   │   ├── generate-schema.js      # OpenAPI spec generator
│   │   ├── daggh-api.yaml         # Generated specification
│   │   └── copy-to-docs.js        # Automation script
│   └── package.json               # Contains docs:full script
│
└── docs/my-docs/                   # Documentation Site
    ├── static/openapi/
    │   └── daggh-api.yaml         # Copied from DAGGH
    ├── docs/api/                  # Generated by plugin
    │   ├── daggh-api.info.mdx     # API overview page
    │   ├── get-random-movies-*.mdx # Auto-generated endpoints
    │   ├── schemas/               # Schema documentation
    │   └── sidebar.ts             # Auto-generated sidebar
    ├── docusaurus.config.ts       # Plugin configuration
    └── sidebars.ts                # Integrates generated sidebar

🎨 Generated Features​

Interactive API Explorer​

  • Method badges with proper HTTP verb styling
  • Endpoint paths with parameter highlighting
  • Parameter forms with validation and examples
  • Request/Response tabs with JSON formatting
  • Authentication headers with JWT token input
  • Live API testing with real server responses

Schema Documentation​

  • Data model pages for all API schemas
  • Property tables with types and descriptions
  • Example objects with realistic data
  • Nested schema navigation

Professional Styling​

  • Consistent Docusaurus theming
  • Mobile-responsive design
  • Dark/light mode support
  • Syntax highlighting for code examples
  • Loading states and error handling

🔧 Key Configuration Options​

config: {
  daggh: {
    specPath: "static/openapi/daggh-api.yaml",
    outputDir: "docs/api",
    sidebarOptions: {
      groupPathsBy: "tag",              // Group by OpenAPI tags
      categoryLinkSource: "tag"         // Use tag descriptions
    },
    hideSendButton: false,              // Enable "Try it out"
    showSchemas: true,                  // Generate schema pages
    downloadUrl: "/openapi/daggh-api.yaml", // Spec download link
  }
}

✨ Benefits Achieved​

For Developers​

  1. Single Source of Truth: API routes define the documentation
  2. Automatic Updates: Changes in code = changes in docs
  3. Interactive Testing: No need for external tools like Postman
  4. Type Safety: Generated schemas ensure consistency

For Users​

  1. Professional Appearance: Beautiful, modern interface
  2. Easy Navigation: Organized by API sections and tags
  3. Live Testing: Try APIs directly in documentation
  4. Mobile Friendly: Works perfectly on all devices

For Maintenance​

  1. Reduced Manual Work: No more manual doc writing
  2. Always Up-to-Date: Docs can't become stale
  3. Consistent Quality: Generated docs follow best practices
  4. Easy Deployment: Standard Docusaurus build process

🎯 Success Metrics​

  • ✅ Zero manual API documentation - everything is auto-generated
  • ✅ Interactive testing - users can try APIs without leaving docs
  • ✅ Professional appearance - matches modern API doc standards
  • ✅ Single command workflow - npm run docs:full updates everything
  • ✅ Mobile responsive - works beautifully on all devices
  • ✅ Integrated with existing docs - seamless navigation experience

This implementation provides a professional, maintainable, and user-friendly API documentation solution that scales with our platform growth.