@devries-cameron20 / composio-1 / commits / 22c4197fd
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: add Stripe-style inline schema expansion for API reference

- Replace popover-based object rendering with inline collapsible "Show child attributes" / "Hide child attributes" buttons - Render enum values as compact inline badges with "Possible values" label - Handle nullable types (e.g. `nullable boolean`) properly - Custom schema generator to power the new rendering Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Feb 3, 2026 at 12:33 UTC 22c4197fd97ac5e49848b4d1434b9811259add39
3 files changed +540 -1
docs/components/api-page.tsx
+28 -1
@@ -1,5 +1,32 @@
1 import { openapi } from '@/lib/openapi';
2 import { createAPIPage } from 'fumadocs-openapi/ui';
3 import client from './api-page.client';
4 +import { generateSchemaData } from './schema-generator';
5 +import { CustomSchemaUI } from './custom-schema-ui';
6
5 -export const APIPage = createAPIPage(openapi, { client });
7 +export const APIPage = createAPIPage(openapi, {
8 + client,
9 + schemaUI: {
10 + render: (options, ctx) => {
11 + const generated = generateSchemaData(
12 + {
13 + root: options.root,
14 + readOnly: options.readOnly,
15 + writeOnly: options.writeOnly,
16 + },
17 + {
18 + renderMarkdown: ctx.renderMarkdown,
19 + schema: { getRawRef: ctx.schema.getRawRef },
20 + }
21 + );
22 + return (
23 + <CustomSchemaUI
24 + name={options.client.name}
25 + required={options.client.required}
26 + as={options.client.as}
27 + generated={generated}
28 + />
29 + );
30 + },
31 + },
32 +});
docs/components/custom-schema-ui.tsx new
+278
@@ -0,0 +1,278 @@
1 +'use client';
2 +
3 +import {
4 + createContext,
5 + Fragment,
6 + use,
7 + useMemo,
8 + useState,
9 + type ReactNode,
10 +} from 'react';
11 +import {
12 + Collapsible,
13 + CollapsibleContent,
14 + CollapsibleTrigger,
15 +} from 'fumadocs-ui/components/ui/collapsible';
16 +import { cn } from '@/lib/utils';
17 +import { Plus, X } from 'lucide-react';
18 +
19 +// Types from fumadocs-openapi
20 +interface FieldBase {
21 + description?: ReactNode;
22 + infoTags?: ReactNode[];
23 + typeName: string;
24 + aliasName: string;
25 + deprecated?: boolean;
26 + enumValues?: string[];
27 +}
28 +
29 +type SchemaData = FieldBase &
30 + (
31 + | { type: 'primitive' }
32 + | {
33 + type: 'object';
34 + props: { name: string; $type: string; required: boolean }[];
35 + }
36 + | { type: 'array'; item: { $type: string } }
37 + | { type: 'or'; items: { name: string; $type: string }[] }
38 + | { type: 'and'; items: { name: string; $type: string }[] }
39 + );
40 +
41 +interface SchemaUIGeneratedData {
42 + $root: string;
43 + refs: Record<string, SchemaData>;
44 +}
45 +
46 +interface SchemaUIProps {
47 + name: string;
48 + required?: boolean;
49 + as?: 'property' | 'body';
50 + generated: SchemaUIGeneratedData;
51 +}
52 +
53 +const DataContext = createContext<SchemaUIGeneratedData | null>(null);
54 +
55 +function useData() {
56 + const ctx = use(DataContext);
57 + if (!ctx) throw new Error('Missing DataContext');
58 + return ctx;
59 +}
60 +
61 +export function CustomSchemaUI({
62 + name,
63 + required = false,
64 + as = 'property',
65 + generated,
66 +}: SchemaUIProps) {
67 + const schema = generated.refs[generated.$root];
68 + const isProperty = as === 'property' || !isExpandable(schema);
69 +
70 + return (
71 + <DataContext value={generated}>
72 + {isProperty ? (
73 + <SchemaProperty
74 + name={name}
75 + $type={generated.$root}
76 + required={required}
77 + isRoot
78 + />
79 + ) : (
80 + <SchemaContent $type={generated.$root} />
81 + )}
82 + </DataContext>
83 + );
84 +}
85 +
86 +function SchemaContent({
87 + $type,
88 + parentPath = '',
89 +}: {
90 + $type: string;
91 + parentPath?: string;
92 +}) {
93 + const { refs } = useData();
94 + const schema = refs[$type];
95 +
96 + if (schema.type === 'object' && schema.props.length > 0) {
97 + return (
98 + <div className="divide-y divide-fd-border">
99 + {schema.props.map((prop) => (
100 + <SchemaProperty
101 + key={prop.name}
102 + name={prop.name}
103 + $type={prop.$type}
104 + required={prop.required}
105 + parentPath={parentPath}
106 + />
107 + ))}
108 + </div>
109 + );
110 + }
111 +
112 + if (schema.type === 'array') {
113 + return <SchemaContent $type={schema.item.$type} parentPath={parentPath} />;
114 + }
115 +
116 + if (schema.type === 'or' && schema.items.length > 0) {
117 + return (
118 + <div className="space-y-2">
119 + <p className="text-xs text-fd-muted-foreground">One of:</p>
120 + {schema.items.map((item, i) => (
121 + <div key={item.$type} className="pl-3 border-l-2 border-fd-border">
122 + <span className="text-sm font-medium">{item.name}</span>
123 + {isExpandable(refs[item.$type]) && (
124 + <ExpandableContent $type={item.$type} parentPath={parentPath} />
125 + )}
126 + </div>
127 + ))}
128 + </div>
129 + );
130 + }
131 +
132 + return null;
133 +}
134 +
135 +function SchemaProperty({
136 + name,
137 + $type,
138 + required,
139 + parentPath = '',
140 + isRoot = false,
141 +}: {
142 + name: string;
143 + $type: string;
144 + required: boolean;
145 + parentPath?: string;
146 + isRoot?: boolean;
147 +}) {
148 + const { refs } = useData();
149 + const schema = refs[$type];
150 + const fullPath = parentPath ? `${parentPath}.${name}` : name;
151 +
152 + const hasChildren = isExpandable(schema);
153 + const typeDisplay = getTypeDisplay(schema);
154 +
155 + return (
156 + <div className={cn('py-4', !isRoot && 'first:pt-0')}>
157 + {/* Property header */}
158 + <div className="flex flex-wrap items-center gap-2">
159 + <span className="font-medium font-mono text-fd-foreground">
160 + {name}
161 + </span>
162 + <span className="text-sm font-mono text-fd-muted-foreground">
163 + {typeDisplay}
164 + </span>
165 + {required && (
166 + <span className="text-xs text-red-400 font-medium">Required</span>
167 + )}
168 + {schema.deprecated && (
169 + <span className="text-xs bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 px-1.5 py-0.5 rounded">
170 + Deprecated
171 + </span>
172 + )}
173 + </div>
174 +
175 + {/* Description */}
176 + {schema.description && (
177 + <div className="mt-2 text-sm text-fd-muted-foreground prose-no-margin">
178 + {schema.description}
179 + </div>
180 + )}
181 +
182 + {/* Info tags */}
183 + {schema.infoTags && schema.infoTags.length > 0 && (
184 + <div className="flex flex-row gap-2 flex-wrap mt-2">
185 + {schema.infoTags.map((tag, i) => (
186 + <Fragment key={i}>{tag}</Fragment>
187 + ))}
188 + </div>
189 + )}
190 +
191 + {/* Enum values */}
192 + {schema.enumValues && schema.enumValues.length > 0 && (
193 + <EnumValues values={schema.enumValues} />
194 + )}
195 +
196 + {/* Expandable child attributes */}
197 + {hasChildren && (
198 + <ExpandableContent $type={$type} parentPath={fullPath} />
199 + )}
200 + </div>
201 + );
202 +}
203 +
204 +function EnumValues({ values }: { values: string[] }) {
205 + return (
206 + <div className="mt-2">
207 + <span className="text-xs text-fd-muted-foreground">Possible values:</span>
208 + <div className="mt-1.5 flex flex-wrap gap-1.5">
209 + {values.map((value) => (
210 + <code
211 + key={value}
212 + className="rounded border border-fd-border px-1.5 py-0.5 text-xs font-mono text-fd-muted-foreground"
213 + >
214 + {value}
215 + </code>
216 + ))}
217 + </div>
218 + </div>
219 + );
220 +}
221 +
222 +function ExpandableContent({
223 + $type,
224 + parentPath,
225 +}: {
226 + $type: string;
227 + parentPath: string;
228 +}) {
229 + const [isOpen, setIsOpen] = useState(false);
230 + const { refs } = useData();
231 + const schema = refs[$type];
232 +
233 + const childCount = getChildCount(schema);
234 + const label = schema.type === 'array' ? 'item properties' : 'child attributes';
235 +
236 + return (
237 + <Collapsible open={isOpen} onOpenChange={setIsOpen} className="mt-3">
238 + <CollapsibleTrigger className="group flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-lg border border-fd-border bg-fd-card hover:bg-fd-accent/50 transition-colors">
239 + {isOpen ? (
240 + <>
241 + <X className="h-4 w-4" />
242 + Hide {label}
243 + </>
244 + ) : (
245 + <>
246 + <Plus className="h-4 w-4" />
247 + Show {childCount > 0 ? `${childCount} ` : ''}{label}
248 + </>
249 + )}
250 + </CollapsibleTrigger>
251 + <CollapsibleContent>
252 + <div className="mt-2 pl-4 border-l-2 border-fd-border">
253 + <SchemaContent $type={$type} parentPath={parentPath} />
254 + </div>
255 + </CollapsibleContent>
256 + </Collapsible>
257 + );
258 +}
259 +
260 +function isExpandable(schema: SchemaData): boolean {
261 + if (schema.type === 'object' && schema.props.length > 0) return true;
262 + if (schema.type === 'array') return true;
263 + if ((schema.type === 'or' || schema.type === 'and') && schema.items.length > 0) return true;
264 + return false;
265 +}
266 +
267 +function getTypeDisplay(schema: SchemaData): string {
268 + if (schema.type === 'array') {
269 + return `array of ${schema.aliasName}`;
270 + }
271 + return schema.typeName;
272 +}
273 +
274 +function getChildCount(schema: SchemaData): number {
275 + if (schema.type === 'object') return schema.props.length;
276 + if (schema.type === 'or' || schema.type === 'and') return schema.items.length;
277 + return 0;
278 +}
docs/components/schema-generator.tsx new
+234
@@ -0,0 +1,234 @@
1 +import type { ReactNode } from 'react';
2 +
3 +// Types matching fumadocs-openapi internal structure
4 +interface FieldBase {
5 + description?: ReactNode;
6 + infoTags?: ReactNode[];
7 + typeName: string;
8 + aliasName: string;
9 + deprecated?: boolean;
10 + enumValues?: string[];
11 +}
12 +
13 +export type SchemaData = FieldBase &
14 + (
15 + | { type: 'primitive' }
16 + | {
17 + type: 'object';
18 + props: { name: string; $type: string; required: boolean }[];
19 + }
20 + | { type: 'array'; item: { $type: string } }
21 + | { type: 'or'; items: { name: string; $type: string }[] }
22 + | { type: 'and'; items: { name: string; $type: string }[] }
23 + );
24 +
25 +export interface SchemaUIGeneratedData {
26 + $root: string;
27 + refs: Record<string, SchemaData>;
28 +}
29 +
30 +// Simplified schema type (subset of OpenAPI schema)
31 +// eslint-disable-next-line @typescript-eslint/no-explicit-any
32 +type SimpleSchema = any;
33 +
34 +interface RenderContext {
35 + renderMarkdown: (text: string) => ReactNode;
36 + schema: {
37 + getRawRef: (obj: object) => string | undefined;
38 + };
39 +}
40 +
41 +interface SchemaUIOptions {
42 + root: SimpleSchema;
43 + readOnly?: boolean;
44 + writeOnly?: boolean;
45 +}
46 +
47 +export function generateSchemaData(
48 + options: SchemaUIOptions,
49 + ctx: RenderContext
50 +): SchemaUIGeneratedData {
51 + const refs: Record<string, SchemaData> = {};
52 + let counter = 0;
53 + const autoIds = new WeakMap<object, string>();
54 +
55 + function getSchemaId(schema: SimpleSchema): string {
56 + if (typeof schema === 'boolean') return String(schema);
57 + if (typeof schema !== 'object' || schema === null) return `__${counter++}`;
58 + const raw = ctx.schema.getRawRef(schema);
59 + if (raw) return raw;
60 + const prev = autoIds.get(schema);
61 + if (prev) return prev;
62 + const generated = `__${counter++}`;
63 + autoIds.set(schema, generated);
64 + return generated;
65 + }
66 +
67 + function getTypeName(schema: SimpleSchema): string {
68 + if (!schema || typeof schema !== 'object') return 'any';
69 + if (schema.$ref) {
70 + const refName = schema.$ref.split('/').pop() || 'object';
71 + return refName;
72 + }
73 + if (schema.type === 'array' && schema.items) {
74 + return `${getTypeName(schema.items)}[]`;
75 + }
76 + if (schema.oneOf || schema.anyOf) {
77 + const variants = schema.oneOf || schema.anyOf || [];
78 + return variants.map((v: SimpleSchema) => getTypeName(v)).join(' | ');
79 + }
80 + if (schema.enum) {
81 + return 'enum';
82 + }
83 + if (Array.isArray(schema.type)) {
84 + const isNullable = schema.type.includes('null');
85 + const types = schema.type.filter((t: string) => t !== 'null');
86 + const typeName = types.join(' | ') || 'any';
87 + return isNullable ? `nullable ${typeName}` : typeName;
88 + }
89 + return schema.type || 'any';
90 + }
91 +
92 + function isVisible(schema: SimpleSchema): boolean {
93 + if (!schema || typeof schema !== 'object') return true;
94 + if (schema.writeOnly) return options.writeOnly ?? false;
95 + if (schema.readOnly) return options.readOnly ?? false;
96 + return true;
97 + }
98 +
99 + function processSchema(schema: SimpleSchema): string {
100 + if (!schema || typeof schema !== 'object') {
101 + const id = `__${counter++}`;
102 + refs[id] = {
103 + type: 'primitive',
104 + typeName: 'any',
105 + aliasName: 'any',
106 + };
107 + return id;
108 + }
109 +
110 + const id = getSchemaId(schema);
111 + if (id in refs) return id;
112 +
113 + const base: FieldBase = {
114 + description: schema.description
115 + ? ctx.renderMarkdown(schema.description)
116 + : undefined,
117 + infoTags: generateInfoTags(schema),
118 + typeName: getTypeName(schema),
119 + aliasName: getTypeName(schema),
120 + deprecated: schema.deprecated,
121 + enumValues: schema.enum
122 + ? schema.enum.map((v: unknown) => String(v))
123 + : undefined,
124 + };
125 +
126 + // Handle oneOf/anyOf
127 + if (schema.oneOf || schema.anyOf) {
128 + const variants = schema.oneOf || schema.anyOf || [];
129 + refs[id] = {
130 + ...base,
131 + type: 'or',
132 + items: variants.map((variant: SimpleSchema) => ({
133 + name: getTypeName(variant),
134 + $type: processSchema(variant),
135 + })),
136 + };
137 + return id;
138 + }
139 +
140 + // Handle allOf - merge into single object
141 + if (schema.allOf) {
142 + // Merge all schemas together
143 + const merged: SimpleSchema = { type: 'object', properties: {}, required: [] };
144 + for (const subSchema of schema.allOf) {
145 + if (subSchema.properties) {
146 + Object.assign(merged.properties, subSchema.properties);
147 + }
148 + if (subSchema.required) {
149 + merged.required.push(...subSchema.required);
150 + }
151 + }
152 + if (Object.keys(merged.properties).length > 0) {
153 + const props = Object.entries(merged.properties)
154 + .filter(([_, propSchema]) => isVisible(propSchema))
155 + .map(([name, propSchema]) => ({
156 + name,
157 + $type: processSchema(propSchema),
158 + required: merged.required.includes(name),
159 + }));
160 + refs[id] = {
161 + ...base,
162 + type: 'object',
163 + props,
164 + };
165 + return id;
166 + }
167 + }
168 +
169 + // Handle object
170 + if ((schema.type === 'object' || schema.properties) && schema.properties) {
171 + const required = schema.required || [];
172 + const props = Object.entries(schema.properties)
173 + .filter(([_, propSchema]) => isVisible(propSchema))
174 + .map(([name, propSchema]) => ({
175 + name,
176 + $type: processSchema(propSchema as SimpleSchema),
177 + required: required.includes(name),
178 + }));
179 +
180 + refs[id] = {
181 + ...base,
182 + type: 'object',
183 + props,
184 + };
185 + return id;
186 + }
187 +
188 + // Handle array
189 + if (schema.type === 'array' && schema.items) {
190 + refs[id] = {
191 + ...base,
192 + type: 'array',
193 + item: { $type: processSchema(schema.items) },
194 + };
195 + return id;
196 + }
197 +
198 + // Primitive type
199 + refs[id] = {
200 + ...base,
201 + type: 'primitive',
202 + };
203 + return id;
204 + }
205 +
206 + function generateInfoTags(schema: SimpleSchema): ReactNode[] {
207 + const tags: ReactNode[] = [];
208 +
209 + if (schema.default !== undefined) {
210 + tags.push(
211 + <div key="default" className="bg-fd-secondary border rounded-lg text-xs p-1.5 shadow-md">
212 + <span className="font-medium me-2">Default</span>
213 + <code className="text-fd-muted-foreground">{JSON.stringify(schema.default)}</code>
214 + </div>
215 + );
216 + }
217 +
218 + if (schema.format) {
219 + tags.push(
220 + <div key="format" className="bg-fd-secondary border rounded-lg text-xs p-1.5 shadow-md">
221 + <span className="font-medium me-2">Format</span>
222 + <code className="text-fd-muted-foreground">{schema.format}</code>
223 + </div>
224 + );
225 + }
226 +
227 + // Enum values are rendered separately in the UI, not as an info tag
228 +
229 + return tags;
230 + }
231 +
232 + const $root = processSchema(options.root);
233 + return { $root, refs };
234 +}