@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
md 185 lines 9.96 KB
Rendered Raw
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)