Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: disable playground and document API reference customizations

Sushmithamallesh9e5a3f312560
diff --git a/docs/.claude/context/api-reference.md b/docs/.claude/context/api-reference.md
new file mode 100644
index 000000000..844cfc669
--- /dev/null
+++ b/docs/.claude/context/api-reference.md
@@ -0,0 +1,60 @@
+# API Reference Customization
+
+The API reference is auto-generated from `public/openapi.json` using [fumadocs-openapi](https://fumadocs.dev/docs/openapi). We customize the rendering with hooks and CSS overrides that depend on fumadocs-openapi internals.
+
+**When upgrading fumadocs-openapi, verify all customizations below still work.**
+
+## Architecture
+
+```
+public/openapi.json ← Auto-fetched from backend (don't edit manually)
+components/api-page.tsx ← createAPIPage config, schema render hook
+components/api-page.client.tsx ← Client-side playground config
+components/schema-generator.tsx ← Server-side: walks OpenAPI schema → SchemaUIGeneratedData
+components/custom-schema-ui.tsx ← Client-side: renders schemas with inline expansion
+app/global.css ← CSS overrides targeting fumadocs-openapi classes
+```
+
+## Custom Schema Rendering
+
+We replace fumadocs-openapi's default popover-based schema rendering with Stripe-style inline expandable sections.
+
+### `api-page.tsx`
+- `schemaUI.render` hook: intercepts all schema rendering
+- Returns `null` for `#/components/schemas/Error` to hide redundant error schemas
+- Passes `isResponse` flag (derived from `readOnly`/`writeOnly`) to hide "Required" labels on response fields
+- `generateTypeScriptSchema: false` disables the TypeScript Definitions copy box
+- `playground: { enabled: false }` disables the API playground (disabled because the OpenAPI spec has issues like kitchen-sink schemas that make the playground unusable)
+
+### `schema-generator.tsx`
+- Server component that walks OpenAPI schemas into a normalized `SchemaUIGeneratedData` structure
+- Handles: objects, arrays, oneOf/anyOf, allOf (merged), enums, nullable types
+- Generates info tags for `default` (skips `{}` and `[]`) and `format`
+- Uses `ctx.schema.getRawRef` for schema identity, falls back to auto-generated IDs
+
+### `custom-schema-ui.tsx`
+- Client component (`'use client'`) with Radix Collapsible for expand/collapse
+- `ResponseContext` threads `isResponse` down to suppress "Required" on response fields
+- `isExpandable()` checks if schemas have actual nested structure (avoids useless expand buttons for primitive unions like `string | string[]`)
+- Enums render as compact inline badges with "Possible values:" label
+
+## CSS Overrides (fragile on upgrade)
+
+All in `app/global.css` under the "OpenAPI Reference" section. These target fumadocs-openapi's internal class structure because no hooks exist for these customizations. Parameter fields (Path/Query/Header) and content type labels are rendered by built-in components with no render hooks.
+
+| Rule | Purpose | Why CSS-only |
+|------|---------|-------------|
+| Hide `span.text-red-400` / `span.text-fd-muted-foreground` | Remove default `*` and `?` field indicators | Parameter fields rendered by built-in components, no hook available |
+| `::after` with `content: "Required"` | Add explicit "Required" label for required fields | Same as above |
+| `div.border.rounded-lg:not(:has(*))` | Hide empty schema wrapper divs (when Error schema returns null) | Wrapper div rendered outside `schemaUI.render` hook |
+| `p.text-fd-muted-foreground.not-prose:has(> code.text-xs)` | Hide `application/json` content type labels | No hook to control content type display |
+
+## OpenAPI Spec Notes
+
+- Spec is OAS 3.0.0 with 60 endpoints
+- All error responses (400, 401, 403, 404, 500, etc.) use identical `#/components/schemas/Error` schema
+- Error descriptions vary per endpoint and are useful (e.g., 410 means different things on different endpoints)
+- `info.description` is empty (backend issue)
+- 0/60 endpoints have response examples (backend issue)
+- `nullable: true` (OAS 3.0) is converted by fumadocs-openapi's dereferencer
+- Some properties named `deprecated` are required fields (spec issue, not the OpenAPI deprecated flag)
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 61a8b7b4e..7a3fa05e3 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -35,6 +35,7 @@ Detailed documentation for Claude is organized in `.claude/`:
- [fumadocs.md](.claude/context/fumadocs.md) - Framework patterns, design tokens, MDX components
- [twoslash.md](.claude/context/twoslash.md) - TypeScript code block type checking
- [sdk-reference.md](.claude/context/sdk-reference.md) - SDK doc generation
+- [api-reference.md](.claude/context/api-reference.md) - API reference customizations (schema rendering, CSS overrides, upgrade notes)
### Guides (How-To)
- [changelog.md](.claude/guides/changelog.md) - Writing changelog entries
diff --git a/docs/app/global.css b/docs/app/global.css
index 384eaaf56..aa62da899 100644
--- a/docs/app/global.css
+++ b/docs/app/global.css
@@ -498,6 +498,7 @@ p.text-fd-muted-foreground.not-prose:has(> code.text-xs) {
display: none;
}
+
/* ==========================================================================
Table of Contents (Right Sidebar)
========================================================================== */
diff --git a/docs/components/api-page.tsx b/docs/components/api-page.tsx
index 0770ca471..e7243fc20 100644
--- a/docs/components/api-page.tsx
+++ b/docs/components/api-page.tsx
@@ -7,6 +7,7 @@ import { CustomSchemaUI } from './custom-schema-ui';
export const APIPage = createAPIPage(openapi, {
client,
generateTypeScriptSchema: false,
+ playground: { enabled: false },
schemaUI: {
render: (options, ctx) => {
// Skip rendering the shared Error schema on error responses -