@devries-cameron20 / composio-1 / commits / 9e5a3f312
Fork 0

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

Disable the API playground (spec quality issues make it unusable). Add documentation for all API reference customizations including why CSS overrides are necessary (no hooks available for parameter field indicators and content type labels). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Feb 4, 2026 at 13:15 UTC 9e5a3f3125606b410b4033fc9009ba62e2a2ed60
4 files changed +63
docs/.claude/context/api-reference.md new
+60
@@ -0,0 +1,60 @@
1 +# API Reference Customization
2 +
3 +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.
4 +
5 +**When upgrading fumadocs-openapi, verify all customizations below still work.**
6 +
7 +## Architecture
8 +
9 +```
10 +public/openapi.json ← Auto-fetched from backend (don't edit manually)
11 +components/api-page.tsx ← createAPIPage config, schema render hook
12 +components/api-page.client.tsx ← Client-side playground config
13 +components/schema-generator.tsx ← Server-side: walks OpenAPI schema → SchemaUIGeneratedData
14 +components/custom-schema-ui.tsx ← Client-side: renders schemas with inline expansion
15 +app/global.css ← CSS overrides targeting fumadocs-openapi classes
16 +```
17 +
18 +## Custom Schema Rendering
19 +
20 +We replace fumadocs-openapi's default popover-based schema rendering with Stripe-style inline expandable sections.
21 +
22 +### `api-page.tsx`
23 +- `schemaUI.render` hook: intercepts all schema rendering
24 +- Returns `null` for `#/components/schemas/Error` to hide redundant error schemas
25 +- Passes `isResponse` flag (derived from `readOnly`/`writeOnly`) to hide "Required" labels on response fields
26 +- `generateTypeScriptSchema: false` disables the TypeScript Definitions copy box
27 +- `playground: { enabled: false }` disables the API playground (disabled because the OpenAPI spec has issues like kitchen-sink schemas that make the playground unusable)
28 +
29 +### `schema-generator.tsx`
30 +- Server component that walks OpenAPI schemas into a normalized `SchemaUIGeneratedData` structure
31 +- Handles: objects, arrays, oneOf/anyOf, allOf (merged), enums, nullable types
32 +- Generates info tags for `default` (skips `{}` and `[]`) and `format`
33 +- Uses `ctx.schema.getRawRef` for schema identity, falls back to auto-generated IDs
34 +
35 +### `custom-schema-ui.tsx`
36 +- Client component (`'use client'`) with Radix Collapsible for expand/collapse
37 +- `ResponseContext` threads `isResponse` down to suppress "Required" on response fields
38 +- `isExpandable()` checks if schemas have actual nested structure (avoids useless expand buttons for primitive unions like `string | string[]`)
39 +- Enums render as compact inline badges with "Possible values:" label
40 +
41 +## CSS Overrides (fragile on upgrade)
42 +
43 +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.
44 +
45 +| Rule | Purpose | Why CSS-only |
46 +|------|---------|-------------|
47 +| 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 |
48 +| `::after` with `content: "Required"` | Add explicit "Required" label for required fields | Same as above |
49 +| `div.border.rounded-lg:not(:has(*))` | Hide empty schema wrapper divs (when Error schema returns null) | Wrapper div rendered outside `schemaUI.render` hook |
50 +| `p.text-fd-muted-foreground.not-prose:has(> code.text-xs)` | Hide `application/json` content type labels | No hook to control content type display |
51 +
52 +## OpenAPI Spec Notes
53 +
54 +- Spec is OAS 3.0.0 with 60 endpoints
55 +- All error responses (400, 401, 403, 404, 500, etc.) use identical `#/components/schemas/Error` schema
56 +- Error descriptions vary per endpoint and are useful (e.g., 410 means different things on different endpoints)
57 +- `info.description` is empty (backend issue)
58 +- 0/60 endpoints have response examples (backend issue)
59 +- `nullable: true` (OAS 3.0) is converted by fumadocs-openapi's dereferencer
60 +- Some properties named `deprecated` are required fields (spec issue, not the OpenAPI deprecated flag)
docs/CLAUDE.md
+1
@@ -35,6 +35,7 @@ Detailed documentation for Claude is organized in `.claude/`:
35 - [fumadocs.md](.claude/context/fumadocs.md) - Framework patterns, design tokens, MDX components
36 - [twoslash.md](.claude/context/twoslash.md) - TypeScript code block type checking
37 - [sdk-reference.md](.claude/context/sdk-reference.md) - SDK doc generation
38 +- [api-reference.md](.claude/context/api-reference.md) - API reference customizations (schema rendering, CSS overrides, upgrade notes)
39
40 ### Guides (How-To)
41 - [changelog.md](.claude/guides/changelog.md) - Writing changelog entries
docs/app/global.css
+1
@@ -498,6 +498,7 @@ p.text-fd-muted-foreground.not-prose:has(> code.text-xs) {
498 display: none;
499 }
500
501 +
502 /* ==========================================================================
503 Table of Contents (Right Sidebar)
504 ========================================================================== */
docs/components/api-page.tsx
+1
@@ -7,6 +7,7 @@ import { CustomSchemaUI } from './custom-schema-ui';
7 export const APIPage = createAPIPage(openapi, {
8 client,
9 generateTypeScriptSchema: false,
10 + playground: { enabled: false },
11 schemaUI: {
12 render: (options, ctx) => {
13 // Skip rendering the shared Error schema on error responses -