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
+}