Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 ← v3.1 spec (auto-fetched, don't edit manually) |
| 11 | public/openapi-v3.json ← v3.0 spec (auto-fetched, don't edit manually) |
| 12 | components/api-page.tsx ← createOpenAPIPage config, schema render hook ('use client') |
| 13 | components/schema-generator.tsx ← walks OpenAPI schema → SchemaUIGeneratedData |
| 14 | components/custom-schema-ui.tsx ← renders schemas with inline expansion |
| 15 | lib/openapi.ts ← createOpenAPI instances + `no_auth` sentinel normalization |
| 16 | lib/openapi-deref.ts ← inlines in-document $refs for the llms.mdx generator |
| 17 | lib/openapi-slice.ts ← narrows the document to one page before it crosses to the client |
| 18 | app/global.css ← CSS overrides targeting fumadocs-openapi classes |
| 19 | ``` |
| 20 | |
| 21 | ## Bundled document handling |
| 22 | |
| 23 | `<OpenAPIPage />` is a client component, and `getOpenAPIPageProps()` carries a |
| 24 | bundled OpenAPI document in `payload.bundled`. |
| 25 | |
| 26 | - In-document `$ref`s survive in the bundled document. Code outside the render |
| 27 | hook must resolve them: the llms.mdx route inlines them via |
| 28 | `lib/openapi-deref.ts`, and the schema generator reads through them with |
| 29 | `ctx.schema.resolve`. |
| 30 | - Sending the entire document across the client boundary on every page is |
| 31 | wasteful. `lib/openapi-slice.ts` narrows it to the operations a page renders. |
| 32 | |
| 33 | ## Custom Schema Rendering |
| 34 | |
| 35 | We replace fumadocs-openapi's default popover-based schema rendering with Stripe-style inline expandable sections. |
| 36 | |
| 37 | ### `api-page.tsx` |
| 38 | - `schemaUI.render` hook: intercepts all schema rendering |
| 39 | - Returns `null` for `#/components/schemas/Error` to hide redundant error schemas |
| 40 | - Passes an `isResponse` flag to hide "Required" labels on response fields. It is |
| 41 | derived from `client.name === 'response'`, NOT from `readOnly`: GET parameters |
| 42 | and request bodies also set `readOnly`, so it cannot distinguish responses. |
| 43 | - `generateTypeScriptDefinitions: false` disables the TypeScript Definitions copy box |
| 44 | - `playground: { enabled: true }` enables the interactive API playground (requests are proxied through `/api/proxy`) |
| 45 | |
| 46 | ### `schema-generator.tsx` |
| 47 | - Walks OpenAPI schemas into a normalized `SchemaUIGeneratedData` structure. Runs on |
| 48 | the client because `api-page.tsx` is a client component. |
| 49 | - Handles: objects, arrays, oneOf/anyOf, allOf (merged), enums, nullable types |
| 50 | - Generates info tags for `default` (skips `{}` and `[]`) and `format` |
| 51 | - Derives schema identity from the raw node's `$ref` (local `getRawRef` in |
| 52 | `api-page.tsx`), falling back to auto-generated IDs, then resolves the node with |
| 53 | `ctx.schema.resolve` before reading its contents. Identity must come from the raw |
| 54 | node or `$ref`-keyed dedup breaks. |
| 55 | |
| 56 | ### `custom-schema-ui.tsx` |
| 57 | - Client component (`'use client'`) with Radix Collapsible for expand/collapse |
| 58 | - `ResponseContext` threads `isResponse` down to suppress "Required" on response fields |
| 59 | - `isExpandable()` checks if schemas have actual nested structure (avoids useless expand buttons for primitive unions like `string | string[]`) |
| 60 | - Enums render as compact inline badges with "Possible values:" label |
| 61 | |
| 62 | ## CSS Overrides (fragile on upgrade) |
| 63 | |
| 64 | 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. |
| 65 | |
| 66 | | Rule | Purpose | Why CSS-only | |
| 67 | |------|---------|-------------| |
| 68 | | `p.text-fd-muted-foreground.not-prose:has(> code.text-xs)` | Hide `application/json` content type labels | No hook to control content type display | |
| 69 | |
| 70 | ## API Versioning (v3.0 / v3.1) |
| 71 | |
| 72 | Two API versions are served side-by-side with a Stripe-style version selector in the top nav bar. |
| 73 | |
| 74 | ### URL structure |
| 75 | - **v3.1 (default):** `/reference/...` — e.g. `/reference/api-reference/tools/getTools` |
| 76 | - **v3.0:** `/reference/v3/...` — e.g. `/reference/v3/api-reference/tools/getTools` |
| 77 | - All existing v3.1 URLs are unchanged — no breaking changes. |
| 78 | |
| 79 | ### How it works |
| 80 | |
| 81 | ``` |
| 82 | lib/openapi.ts ← Creates two OpenAPI instances (v3.1 + v3.0) |
| 83 | lib/source.ts ← Combined source: v3.1 at api-reference/, v3.0 at v3/api-reference/ |
| 84 | lib/api-version.ts ← Shared detectApiVersion() utility (single source of truth) |
| 85 | lib/use-api-version.ts ← Client hook wrapping detectApiVersion for React components |
| 86 | lib/filter-api-version.ts ← Tree filter: hides V3 folder for v3.1, lifts V3 children for v3.0 |
| 87 | app/(home)/reference/(v31)/layout.tsx ← v3.1 layout: hardcodes version, renders DocsLayout with filtered tree |
| 88 | app/(home)/reference/v3/layout.tsx ← v3.0 layout: hardcodes version, renders DocsLayout with filtered tree |
| 89 | components/version-selector.tsx ← Dropdown in top nav, navigates between /reference/ ↔ /reference/v3/ |
| 90 | components/api-base-url.tsx ← Dynamic base URL: v3.1 or v3 based on current path |
| 91 | components/api-endpoints-table.tsx ← Endpoint tables in index pages, shows versioned paths |
| 92 | components/version-badge.tsx ← Badge on endpoint pages showing API version |
| 93 | ``` |
| 94 | |
| 95 | Markdown channels (what agents read — see "Version identity in the markdown |
| 96 | channels" below): |
| 97 | |
| 98 | ``` |
| 99 | lib/source.ts ← mdxToCleanMarkdown renders ApiBaseUrl + ApiEndpointsTable for .md |
| 100 | app/llms.mdx/[[...slug]]/route.ts ← openapiPageToMarkdown emits the version pointer + guidance |
| 101 | lib/api-endpoints-table-schema.ts ← shared zod schema for the ApiEndpointsTable prop |
| 102 | lib/api-version-guidance.ts ← the two guidance constants + the tool-path predicate |
| 103 | ``` |
| 104 | |
| 105 | ### Version identity in the markdown channels |
| 106 | |
| 107 | The signals that separate v3.1 from v3.0 (version dropdown, base URL, endpoint |
| 108 | tables, version badge) all live in the **browser** rendering path. Agents read |
| 109 | `.md`, `llms.txt`, `llms-full.txt`, and the Context7 ingest, none of which walk |
| 110 | that path — so every one of those signals used to be dropped, and the only |
| 111 | concrete request an agent could find was a v3.0 curl example. |
| 112 | |
| 113 | There are **two markdown renderers**, and they fail differently: |
| 114 | |
| 115 | | Surface | Renderer | |
| 116 | |---------|----------| |
| 117 | | MDX pages under `/reference/**` (incl. `reference.md`, tag pages) | `getLLMText` + `mdxToCleanMarkdown` in `lib/source.ts` | |
| 118 | | OpenAPI operation pages (e.g. `getTools.md`) | `openapiPageToMarkdown` in `app/llms.mdx/[[...slug]]/route.ts` | |
| 119 | |
| 120 | A fix in `lib/source.ts` alone does not reach operation pages. |
| 121 | |
| 122 | **Composition rule** — the rule most likely to be violated by the next person |
| 123 | adding a channel: |
| 124 | |
| 125 | - **Broad channels** (`SESSION_GUARDRAILS`, `DIRECT_EXECUTION_GUARDRAILS`) |
| 126 | compose **both** `REST_VERSION_GUIDANCE` and `TOOL_VERSION_GUIDANCE`. Their |
| 127 | reader may call any endpoint. |
| 128 | - **OpenAPI operation pages** get `REST_VERSION_GUIDANCE` always, and |
| 129 | `TOOL_VERSION_GUIDANCE` only when `isToolVersionPath` matches. They do **not** |
| 130 | get `SESSION_GUARDRAILS` — it is about SDK code generation, and since it |
| 131 | composes the tool-version text it would force it onto operations it does not |
| 132 | apply to. |
| 133 | - **Top notes** (`getLLMText`, `openapiPageToMarkdown`) carry **neither**. They |
| 134 | are a pointer only: which version, the base URL, the cross-version link. The |
| 135 | guidance already appears further down the same response. |
| 136 | |
| 137 | Two more rules: |
| 138 | |
| 139 | - **Any new version-dependent rendering must go through `detectApiVersion`** |
| 140 | (`lib/api-version.ts`), never an inline `/reference/v3/` string test. Moving |
| 141 | the legacy tree's URL should be a one-line change in that file. |
| 142 | - **Normalization is `isToolVersionPath`'s job, and only its job.** Callers pass |
| 143 | the raw spec path key verbatim (`/api/v3.1/tools/{tool_slug}`, with the `/api` |
| 144 | segment). It strips `/api/v3.1` before `/api/v3` and compares by exact set |
| 145 | membership — `/tools/enum`, `/tools/execute/proxy`, and |
| 146 | `tool_router/…/tools` all mention `tools` and none of them is affected. |
| 147 | |
| 148 | ### Content structure |
| 149 | |
| 150 | v3.0 has its own complete page tree under `content/reference/v3/`: |
| 151 | - `v3/index.mdx` — Overview (with v3 links and base URL) |
| 152 | - `v3/authentication.mdx` — Auth docs (with v3 curl examples) |
| 153 | - `v3/rate-limits.mdx`, `v3/errors.mdx` — Duplicated non-API pages |
| 154 | - `v3/api-reference/` — Auto-generated index pages + OpenAPI endpoint pages |
| 155 | - `v3/meta.json` — Sidebar ordering |
| 156 | |
| 157 | SDK Reference is version-independent and shared across both trees. Meta Tools moved out of the reference tree entirely — they now live under the Toolkits tab at `/toolkits/meta-tools`. |
| 158 | |
| 159 | ### Version selector behavior |
| 160 | - On an API page: swaps `/reference/` ↔ `/reference/v3/` (stays on same endpoint/category) |
| 161 | - On overview (`/reference`): navigates to `/reference/v3` (v3 has its own overview) |
| 162 | - Full page reload on every version switch (server re-renders layout with filtered tree) |
| 163 | |
| 164 | ### Auto-generation pipeline (`docs-update-data.yml`) |
| 165 | 1. `fetch-openapi.mjs` — fetches both v3.1 and v3.0 specs from backend |
| 166 | 2. `generate-api-index.ts` — generates index pages for both `api-reference/` and `v3/api-reference/` |
| 167 | 3. CI tracks: `openapi.json`, `openapi-v3.json`, `api-reference/`, `v3/api-reference/` |
| 168 | |
| 169 | ### Adding/modifying v3 content |
| 170 | - API endpoint pages are auto-generated from the OpenAPI spec — no manual work needed |
| 171 | - Index pages are auto-generated by `bun run generate:api-index` |
| 172 | - Non-API pages (`v3/index.mdx`, `v3/authentication.mdx`, etc.) are manual copies — update both versions when content changes |
| 173 | - `v3/meta.json` and `v3/api-reference/meta.json` control sidebar ordering |
| 174 | |
| 175 | ## OpenAPI Spec Notes |
| 176 | |
| 177 | - v3.1 spec is OAS 3.0.0 format |
| 178 | - v3.0 spec is also OAS 3.0.0 format with the same tag structure |
| 179 | - All error responses use identical `#/components/schemas/Error` schema |
| 180 | - Error descriptions vary per endpoint and are useful |
| 181 | - `info.description` is empty (backend issue) |
| 182 | - No response examples (backend issue) |
| 183 | - `nullable: true` (OAS 3.0) is converted when fumadocs-openapi dereferences at |
| 184 | render time |
| 185 | - Some properties named `deprecated` are required fields (spec issue, not the OpenAPI deprecated flag) |