OpenAPI Renderer — "Constellation"

A next-generation OpenAPI documentation renderer with an immersive, spatial design. Not a Swagger reskin — a completely different experience.

Run

npm install --registry https://registry.npmjs.org
npm run dev

Features — Scalar Parity & Beyond

✅ Full Documentation (not just Try It)

Every endpoint opens as a two-column detail view:

| Left Column (Docs) | Right Column (Interactive) | |---|---| | Summary + description | Code samples (cURL, JS, Python) | | Authentication requirements | Try It panel with full controls | | Path parameters | Response examples (generated from schema) | | Query parameters | | | Header parameters | | | Cookie parameters | | | Request body (multi media-type) | | | Schema tree (expandable, recursive) | | | Responses (all status codes, headers, body schema) | |

✅ Feature Comparison with Scalar

| Feature | Scalar | This Renderer | |---------|--------|---------------| | API info/hero | ✅ | ✅ Cinematic hero with animated orbs | | Server selector | ✅ | ✅ In hero + Try It panel | | Parameters by type (path/query/header/cookie) | ✅ | ✅ Grouped with types + defaults + enums | | Request body with schema | ✅ | ✅ Media type selector + recursive schema tree | | Response documentation | ✅ | ✅ All status codes + headers + body schema | | Response examples | ✅ | ✅ Auto-generated from schema | | Code samples | ✅ (multi-language) | ✅ 21 languages (cURL, JS, Python, Go, Ruby, PHP, Java, C#, Rust, Swift, Kotlin, Dart, etc.) | | Try It / Test Request | ✅ | ✅ Full: server select, params, headers, body, response timing | | Authentication display | ✅ | ✅ OAuth2 (all flows + PKCE), API Key, Basic, Bearer, prefill config | | Models/Schemas section | ✅ | ✅ Grid layout, expandable properties | | Search | ✅ | ✅ Command palette (⌘K) | | Dark/Light theme | ✅ | ✅ Live toggle | | Sidebar navigation | ✅ (fixed sidebar) | ✅ Fixed sidebar + Floating dock (unique) | | Markdown descriptions | ✅ | ✅ Rendered text | | Operation ID display | ✅ | ✅ Badge in detail header | | Deprecated indicator | ✅ | ✅ Badge on card + detail | | Multiple servers | ✅ | ✅ Hero display + dropdown in Try It | | Customization (runtime) | ❌ (config only) | ✅ Live GUI panel: accent color, radius, toggles, CSS injection | | Animations | Minimal | ✅ Framer Motion: spring physics, 3D tilt, staggered reveals | | Layout | Sidebar + list | ✅ Spatial: full-page hero → scrollable cards → cinematic modals | | Custom CSS injection | ✅ | ✅ | | Export/Download spec | ✅ | ✅ JSON/YAML/both/none | | Webhooks | ✅ | ✅ | | Multiple documents | ✅ | ✅ Per-doc config, slug routing, default selection | | Plugin system | ✅ | ✅ Lifecycle hooks, view slots, extensions, response handlers | | Framework integrations | ✅ (30+) | ✅ 20+ (Express, Fastify, Hono, Koa, Next.js, Nuxt, SvelteKit, Astro, FastAPI, Django, Flask, NestJS, Spring Boot, ASP.NET, Go, Rails, Rust, Elysia, Lambda, Workers, Deno) | | Configuration depth | ✅ (50+ options) | ✅ 50+ options (auth, sorting, routing, events, display, meta, etc.) | | Events/Callbacks | ✅ | ✅ onBeforeRequest, onLoaded, onServerChange, onDocumentSelect, etc. | | Authentication prefill | ✅ | ✅ preferredSecurityScheme, per-scheme config | | Path-based routing | ✅ | ✅ hash + path routing with basePath | | Hidden clients control | ✅ | ✅ Per-language or global | | Tag/Operation sorting | ✅ | ✅ alpha, method, custom comparator |

✅ Unique Features Not in Scalar

• Floating Dock navigation — macOS-style bottom dock instead of sidebar
• 3D tilt effect on endpoint cards (perspective mouse tracking)
• Cinematic endpoint modals — full-screen two-column detail
• Ambient mesh background with animated gradient orbs
• Particle field in hero section
• Live customizer — color picker, border radius, section toggles, CSS in real-time
• Command palette (⌘K) with spring-animated results
• Response timing in Try It panel
• Code sample copy with visual feedback
• Full plugin system — lifecycle hooks, view injection (8 slots), spec extensions, response handlers
• 20+ framework integrations — Express, Fastify, Hono, Koa, Next.js, Nuxt, SvelteKit, Astro, FastAPI, Django, Flask, NestJS, Spring Boot, ASP.NET, Go, Rails, Rust, Elysia, Lambda, Workers, Deno
• Multi-document sources — per-doc config, slug routing, default selection
• 50+ configuration options — auth prefill, sorting, routing, events, display toggles, metadata

Architecture

src/
├── components/
│   ├── OpenAPIRenderer.tsx   # Root — composes all sections
│   ├── Hero.tsx              # Full-viewport animated intro
│   ├── Dock.tsx              # Floating bottom navigation
│   ├── EndpointGroups.tsx    # Tag sections with endpoint list
│   ├── EndpointCard.tsx      # Card + full detail modal (docs + code + try it)
│   ├── ModelsSection.tsx     # Schema models grid
│   ├── CommandPalette.tsx    # ⌘K search spotlight
│   └── Customizer.tsx        # Live appearance controls
├── hooks/                    # Intersection observer, keyboard, theme
├── store/                    # Zustand global state
├── types/                    # Full OpenAPI 3.x TypeScript types
├── utils/                    # Spec parser, helpers, $ref resolver
└── styles/                   # CSS variables, mesh bg, frost glass

Usage

Basic

import { OpenAPIRenderer } from '@ashishkumarpathak/openapi-renderer'

<OpenAPIRenderer
  spec="https://api.example.com/openapi.json"
  config={{
    theme: 'dark',
    showModels: true,
    showSearch: true,
    showTryIt: true,
    animationsEnabled: true,
    expandAllTags: true,
    accentColor: '#7c5cfc',
    borderRadius: 16,
  }}
/>

Multiple Documents (Scalar-Compatible)

<OpenAPIRenderer
  sources={[
    {
      title: 'Users API',
      slug: 'users',
      url: 'https://api.example.com/users/openapi.json',
    },
    {
      title: 'Payments API',
      slug: 'payments',
      url: 'https://api.example.com/payments/openapi.json',
      default: true, // This one loads first
      config: { accentColor: '#10b981' }, // Per-document config
    },
  ]}
  config={{ theme: 'dark' }}
/>

With Authentication Prefill

<OpenAPIRenderer
  spec={mySpec}
  config={{
    authentication: {
      preferredSecurityScheme: 'bearerAuth',
      securitySchemes: {
        bearerAuth: { token: 'your-dev-token' },
        oauth2: {
          flows: {
            authorizationCode: {
              clientId: 'your-client-id',
              usePkce: 'SHA-256',
            },
          },
        },
      },
      persistAuth: true,
    },
    events: {
      onLoaded: (slug) => console.log('Loaded:', slug),
      onServerChange: (server) => console.log('Server:', server),
    },
  }}
/>

With Plugins

import { OpenAPIRenderer, registerPlugin } from '@ashishkumarpathak/openapi-renderer'

// Register before rendering
registerPlugin(() => ({
  name: 'my-analytics',
  hooks: {
    onSpecLoaded: ({ spec }) => analytics.track('docs_viewed', { api: spec.info.title }),
    onBeforeRequest: (req) => {
      req.headers['X-Tracking-Id'] = generateId()
      return req
    },
  },
  views: {
    'content.end': [{
      component: () => <footer>Need help? <a href="/support">Contact us</a></footer>,
    }],
  },
}))

<OpenAPIRenderer spec={mySpec} />

Framework Integration (Express)

import { expressMiddleware } from '@ashishkumarpathak/openapi-renderer/integrations'

app.use('/docs', expressMiddleware({
  spec: '/api/openapi.json',
  title: 'My API',
  theme: 'dark',
}))

CSS Variables

:root {
  --oar-bg: #050508;
  --oar-surface: #0c0c12;
  --oar-surface-elevated: #13131d;
  --oar-accent: #7c5cfc;
  --oar-accent-2: #5ce1e6;
  --oar-text: #e8e8f0;
  --oar-text-dim: #8888a0;
  --oar-text-muted: #55556a;
  --oar-border: rgba(255, 255, 255, 0.06);
  --oar-get: #5ce1e6;
  --oar-post: #7c5cfc;
  --oar-put: #ffb347;
  --oar-delete: #ff6b6b;
  --oar-patch: #c77dff;
  --oar-font: 'Inter', system-ui;
  --oar-font-mono: 'JetBrains Mono', monospace;
}

License

MIT