Skip to content

OPENAPI_SETUP.md

Latest commit

 

History

History
124 lines (87 loc) · 5.31 KB

OPENAPI_SETUP.md

File metadata and controls

124 lines (87 loc) · 5.31 KB

OpenAPI Playground Setup - Implementation Summary

This document explains what was implemented to create an interactive OpenAPI playground using Fumadocs.

What Was Done

1. Installed Required Packages

  • fumadocs-openapi: The official Fumadocs OpenAPI integration package
  • shiki: Syntax highlighting library (required dependency)

2. Added OpenAPI CSS Styles

  • Updated app/global.css to include @import 'fumadocs-openapi/css/preset.css'
  • This provides the necessary styling for the OpenAPI playground components

3. Created OpenAPI Instance (lib/openapi.ts)

  • Created a server-side OpenAPI instance that loads your openapi.yml file
  • This instance is used to generate API documentation pages dynamically

4. Created API Page Components

  • components/api-page.tsx: Server component that creates the API page using Fumadocs' createAPIPage function
  • components/api-page.client.tsx: Client component for client-side configuration (currently empty, can be extended later)

5. Integrated OpenAPI with Source Loader (lib/source.ts)

  • Updated the source loader to use multiple() to combine:
    • Your existing MDX docs (docs.toFumadocsSource())
    • OpenAPI-generated pages (openapiSource())
  • Added openapiPlugin() to the plugins array
  • This creates virtual pages from your OpenAPI spec under the /docs/openapi/ path

6. Updated Docs Page Handler (app/docs/[[...slug]]/page.tsx)

  • Added logic to detect OpenAPI pages (page.data.type === 'openapi')
  • When an OpenAPI page is detected, it renders the APIPage component with interactive playground
  • Regular MDX pages continue to work as before

7. Updated MDX Components (mdx-components.tsx)

  • Added APIPage to the MDX components so it can be used in MDX files if needed
  • This allows you to embed API documentation in regular MDX pages

How It Works

  1. Virtual File Generation: The openapiSource() function reads your openapi.yml file and generates virtual documentation pages for each API endpoint, organized by tags.

  2. Interactive Playground: Each API endpoint page includes:

    • Endpoint information (method, path, description)
    • Interactive request builder with parameter inputs
    • Code samples in multiple languages
    • Response schemas and examples
    • Try-it-out functionality to test API calls

  3. Navigation: OpenAPI pages appear in your docs navigation under /docs/openapi/ with the structure based on your OpenAPI tags.

Accessing the Playground

Once you run bun dev, you can access:

  • Main docs: /docs - Your regular documentation
  • OpenAPI docs: /docs/openapi/... - Auto-generated API documentation with interactive playground

The OpenAPI pages will be organized by the tags defined in your openapi.yml file (e.g., Authentication, Projects, Toolkits, etc.).

Features Included

✅ Interactive API playground with try-it-out functionality
✅ Code samples in multiple programming languages
✅ Request/response schema documentation
✅ Parameter documentation with examples
✅ TypeScript type definitions
✅ Server selection (production, staging, local)
✅ Authentication configuration UI

Next Steps

  1. Run bun dev to start the development server
  2. Navigate to /docs and look for OpenAPI sections in the navigation
  3. Click on any API endpoint to see the interactive playground
  4. Test API calls directly from the browser (make sure CORS is configured on your API server)

Performance Considerations

⚠️ Important: Development vs Production

The slowness you experience is ONLY in development. Users in production will NOT experience it.

See PERFORMANCE_EXPLANATION.md for a detailed explanation.

Quick Summary

Why is rendering slow in development?

The slowness is not because it's local - it's due to the size of your OpenAPI spec:

  • File Size: 1.1MB (1,155,523 bytes)
  • Line Count: 26,323 lines
  • Processing: The entire spec must be parsed, validated, and virtual pages generated for all ~77 endpoints

Development (Local):

  • First request: 5-15 seconds (processes entire spec)
  • Subsequent requests: < 1 second (cached)
  • You experience this slowness during development

Production (Cloud):

  • Build time: 5-15 seconds (happens once during deployment)
  • User requests: < 100ms (serves pre-built static pages)
  • Users experience fast page loads!

How It Works

Your setup uses Static Site Generation (SSG):

  • The generateStaticParams() function pre-generates all pages at build time
  • All OpenAPI processing happens during bun build, not at runtime
  • Users receive pre-built static HTML pages that load instantly

Optimization Tips

  • Development: Accept that first load is slow, but subsequent navigations are fast
  • Production: Run bun build - all processing happens during build, users get fast pages
  • Large Specs: This is expected behavior. The trade-off is comprehensive documentation vs. build time (not user experience)

Customization

You can customize the playground by:

  • Editing components/api-page.client.tsx to add client-side configuration
  • Modifying lib/openapi.ts to change how the OpenAPI spec is loaded
  • Adjusting the baseDir in lib/source.ts to change the URL path for OpenAPI docs