Skip to content

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

Sushmithamallesh22c4197fd97a
diff --git a/docs/components/api-page.tsx b/docs/components/api-page.tsx
index 1728eb797..ed1e571ab 100644
--- a/docs/components/api-page.tsx
+++ b/docs/components/api-page.tsx
@@ -1,5 +1,32 @@
import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import client from './api-page.client';
+import { generateSchemaData } from './schema-generator';
+import { CustomSchemaUI } from './custom-schema-ui';
-export const APIPage = createAPIPage(openapi, { client });
+export const APIPage = createAPIPage(openapi, {
+ client,
+ schemaUI: {
+ render: (options, ctx) => {
+ const generated = generateSchemaData(
+ {
+ root: options.root,
+ readOnly: options.readOnly,
+ writeOnly: options.writeOnly,
+ },
+ {
+ renderMarkdown: ctx.renderMarkdown,
+ schema: { getRawRef: ctx.schema.getRawRef },
+ }
+ );
+ return (
+ <CustomSchemaUI
+ name={options.client.name}
+ required={options.client.required}
+ as={options.client.as}
+ generated={generated}
+ />
+ );
+ },
+ },
+});
diff --git a/docs/components/custom-schema-ui.tsx b/docs/components/custom-schema-ui.tsx
new file mode 100644
index 000000000..9202344a2
--- /dev/null
+++ b/docs/components/custom-schema-ui.tsx
@@ -0,0 +1,278 @@
+'use client';
+
+import {
+ createContext,
+ Fragment,
+ use,
+ useMemo,
+ useState,
+ type ReactNode,
+} from 'react';
+import {
+ Collapsible,
+ CollapsibleContent,
+ CollapsibleTrigger,
+} from 'fumadocs-ui/components/ui/collapsible';
+import { cn } from '@/lib/utils';
+import { Plus, X } from 'lucide-react';
+
+// Types from fumadocs-openapi
+interface FieldBase {
+ description?: ReactNode;
+ infoTags?: ReactNode[];
+ typeName: string;
+ aliasName: string;
+ deprecated?: boolean;
+ enumValues?: string[];
+}
+
+type SchemaData = FieldBase &
+ (
+ | { type: 'primitive' }
+ | {
+ type: 'object';
+ props: { name: string; $type: string; required: boolean }[];
+ }
+ | { type: 'array'; item: { $type: string } }
+ | { type: 'or'; items: { name: string; $type: string }[] }
+ | { type: 'and'; items: { name: string; $type: string }[] }
+ );
+
+interface SchemaUIGeneratedData {
+ $root: string;
+ refs: Record<string, SchemaData>;
+}
+
+interface SchemaUIProps {
+ name: string;
+ required?: boolean;
+ as?: 'property' | 'body';
+ generated: SchemaUIGeneratedData;
+}
+
+const DataContext = createContext<SchemaUIGeneratedData | null>(null);
+
+function useData() {
+ const ctx = use(DataContext);
+ if (!ctx) throw new Error('Missing DataContext');
+ return ctx;
+}
+
+export function CustomSchemaUI({
+ name,
+ required = false,
+ as = 'property',
+ generated,
+}: SchemaUIProps) {
+ const schema = generated.refs[generated.$root];
+ const isProperty = as === 'property' || !isExpandable(schema);
+
+ return (
+ <DataContext value={generated}>
+ {isProperty ? (
+ <SchemaProperty
+ name={name}
+ $type={generated.$root}
+ required={required}
+ isRoot
+ />
+ ) : (
+ <SchemaContent $type={generated.$root} />
+ )}
+ </DataContext>
+ );
+}
+
+function SchemaContent({
+ $type,
+ parentPath = '',
+}: {
+ $type: string;
+ parentPath?: string;
+}) {
+ const { refs } = useData();
+ const schema = refs[$type];
+
+ if (schema.type === 'object' && schema.props.length > 0) {
+ return (
+ <div className="divide-y divide-fd-border">
+ {schema.props.map((prop) => (
+ <SchemaProperty
+ key={prop.name}
+ name={prop.name}
+ $type={prop.$type}
+ required={prop.required}
+ parentPath={parentPath}
+ />
+ ))}
+ </div>
+ );
+ }
+
+ if (schema.type === 'array') {
+ return <SchemaContent $type={schema.item.$type} parentPath={parentPath} />;
+ }
+
+ if (schema.type === 'or' && schema.items.length > 0) {
+ return (
+ <div className="space-y-2">
+ <p className="text-xs text-fd-muted-foreground">One of:</p>
+ {schema.items.map((item, i) => (
+ <div key={item.$type} className="pl-3 border-l-2 border-fd-border">
+ <span className="text-sm font-medium">{item.name}</span>
+ {isExpandable(refs[item.$type]) && (
+ <ExpandableContent $type={item.$type} parentPath={parentPath} />
+ )}
+ </div>
+ ))}
+ </div>
+ );
+ }
+
+ return null;
+}
+
+function SchemaProperty({
+ name,
+ $type,
+ required,
+ parentPath = '',
+ isRoot = false,
+}: {
+ name: string;
+ $type: string;
+ required: boolean;
+ parentPath?: string;
+ isRoot?: boolean;
+}) {
+ const { refs } = useData();
+ const schema = refs[$type];
+ const fullPath = parentPath ? `${parentPath}.${name}` : name;
+
+ const hasChildren = isExpandable(schema);
+ const typeDisplay = getTypeDisplay(schema);
+
+ return (
+ <div className={cn('py-4', !isRoot && 'first:pt-0')}>
+ {/* Property header */}
+ <div className="flex flex-wrap items-center gap-2">
+ <span className="font-medium font-mono text-fd-foreground">
+ {name}
+ </span>
+ <span className="text-sm font-mono text-fd-muted-foreground">
+ {typeDisplay}
+ </span>
+ {required && (
+ <span className="text-xs text-red-400 font-medium">Required</span>
+ )}
+ {schema.deprecated && (
+ <span className="text-xs bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 px-1.5 py-0.5 rounded">
+ Deprecated
+ </span>
+ )}
+ </div>
+
+ {/* Description */}
+ {schema.description && (
+ <div className="mt-2 text-sm text-fd-muted-foreground prose-no-margin">
+ {schema.description}
+ </div>
+ )}
+
+ {/* Info tags */}
+ {schema.infoTags && schema.infoTags.length > 0 && (
+ <div className="flex flex-row gap-2 flex-wrap mt-2">
+ {schema.infoTags.map((tag, i) => (
+ <Fragment key={i}>{tag}</Fragment>
+ ))}
+ </div>
+ )}
+
+ {/* Enum values */}
+ {schema.enumValues && schema.enumValues.length > 0 && (
+ <EnumValues values={schema.enumValues} />
+ )}
+
+ {/* Expandable child attributes */}
+ {hasChildren && (
+ <ExpandableContent $type={$type} parentPath={fullPath} />
+ )}
+ </div>
+ );
+}
+
+function EnumValues({ values }: { values: string[] }) {
+ return (
+ <div className="mt-2">
+ <span className="text-xs text-fd-muted-foreground">Possible values:</span>
+ <div className="mt-1.5 flex flex-wrap gap-1.5">
+ {values.map((value) => (
+ <code
+ key={value}
+ className="rounded border border-fd-border px-1.5 py-0.5 text-xs font-mono text-fd-muted-foreground"
+ >
+ {value}
+ </code>
+ ))}
+ </div>
+ </div>
+ );
+}
+
+function ExpandableContent({
+ $type,
+ parentPath,
+}: {
+ $type: string;
+ parentPath: string;
+}) {
+ const [isOpen, setIsOpen] = useState(false);
+ const { refs } = useData();
+ const schema = refs[$type];
+
+ const childCount = getChildCount(schema);
+ const label = schema.type === 'array' ? 'item properties' : 'child attributes';
+
+ return (
+ <Collapsible open={isOpen} onOpenChange={setIsOpen} className="mt-3">
+ <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">
+ {isOpen ? (
+ <>
+ <X className="h-4 w-4" />
+ Hide {label}
+ </>
+ ) : (
+ <>
+ <Plus className="h-4 w-4" />
+ Show {childCount > 0 ? `${childCount} ` : ''}{label}
+ </>
+ )}
+ </CollapsibleTrigger>
+ <CollapsibleContent>
+ <div className="mt-2 pl-4 border-l-2 border-fd-border">
+ <SchemaContent $type={$type} parentPath={parentPath} />
+ </div>
+ </CollapsibleContent>
+ </Collapsible>
+ );
+}
+
+function isExpandable(schema: SchemaData): boolean {
+ if (schema.type === 'object' && schema.props.length > 0) return true;
+ if (schema.type === 'array') return true;
+ if ((schema.type === 'or' || schema.type === 'and') && schema.items.length > 0) return true;
+ return false;
+}
+
+function getTypeDisplay(schema: SchemaData): string {
+ if (schema.type === 'array') {
+ return `array of ${schema.aliasName}`;
+ }
+ return schema.typeName;
+}
+
+function getChildCount(schema: SchemaData): number {
+ if (schema.type === 'object') return schema.props.length;
+ if (schema.type === 'or' || schema.type === 'and') return schema.items.length;
+ return 0;
+}
diff --git a/docs/components/schema-generator.tsx b/docs/components/schema-generator.tsx
new file mode 100644
index 000000000..b23657cf1
--- /dev/null
+++ b/docs/components/schema-generator.tsx
@@ -0,0 +1,234 @@
+import type { ReactNode } from 'react';
+
+// Types matching fumadocs-openapi internal structure
+interface FieldBase {
+ description?: ReactNode;
+ infoTags?: ReactNode[];
+ typeName: string;
+ aliasName: string;
+ deprecated?: boolean;
+ enumValues?: string[];
+}
+
+export type SchemaData = FieldBase &
+ (
+ | { type: 'primitive' }
+ | {
+ type: 'object';
+ props: { name: string; $type: string; required: boolean }[];
+ }
+ | { type: 'array'; item: { $type: string } }
+ | { type: 'or'; items: { name: string; $type: string }[] }
+ | { type: 'and'; items: { name: string; $type: string }[] }
+ );
+
+export interface SchemaUIGeneratedData {
+ $root: string;
+ refs: Record<string, SchemaData>;
+}
+
+// Simplified schema type (subset of OpenAPI schema)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SimpleSchema = any;
+
+interface RenderContext {
+ renderMarkdown: (text: string) => ReactNode;
+ schema: {
+ getRawRef: (obj: object) => string | undefined;
+ };
+}
+
+interface SchemaUIOptions {
+ root: SimpleSchema;
+ readOnly?: boolean;
+ writeOnly?: boolean;
+}
+
+export function generateSchemaData(
+ options: SchemaUIOptions,
+ ctx: RenderContext
+): SchemaUIGeneratedData {
+ const refs: Record<string, SchemaData> = {};
+ let counter = 0;
+ const autoIds = new WeakMap<object, string>();
+
+ function getSchemaId(schema: SimpleSchema): string {
+ if (typeof schema === 'boolean') return String(schema);
+ if (typeof schema !== 'object' || schema === null) return `__${counter++}`;
+ const raw = ctx.schema.getRawRef(schema);
+ if (raw) return raw;
+ const prev = autoIds.get(schema);
+ if (prev) return prev;
+ const generated = `__${counter++}`;
+ autoIds.set(schema, generated);
+ return generated;
+ }
+
+ function getTypeName(schema: SimpleSchema): string {
+ if (!schema || typeof schema !== 'object') return 'any';
+ if (schema.$ref) {
+ const refName = schema.$ref.split('/').pop() || 'object';
+ return refName;
+ }
+ if (schema.type === 'array' && schema.items) {
+ return `${getTypeName(schema.items)}[]`;
+ }
+ if (schema.oneOf || schema.anyOf) {
+ const variants = schema.oneOf || schema.anyOf || [];
+ return variants.map((v: SimpleSchema) => getTypeName(v)).join(' | ');
+ }
+ if (schema.enum) {
+ return 'enum';
+ }
+ if (Array.isArray(schema.type)) {
+ const isNullable = schema.type.includes('null');
+ const types = schema.type.filter((t: string) => t !== 'null');
+ const typeName = types.join(' | ') || 'any';
+ return isNullable ? `nullable ${typeName}` : typeName;
+ }
+ return schema.type || 'any';
+ }
+
+ function isVisible(schema: SimpleSchema): boolean {
+ if (!schema || typeof schema !== 'object') return true;
+ if (schema.writeOnly) return options.writeOnly ?? false;
+ if (schema.readOnly) return options.readOnly ?? false;
+ return true;
+ }
+
+ function processSchema(schema: SimpleSchema): string {
+ if (!schema || typeof schema !== 'object') {
+ const id = `__${counter++}`;
+ refs[id] = {
+ type: 'primitive',
+ typeName: 'any',
+ aliasName: 'any',
+ };
+ return id;
+ }
+
+ const id = getSchemaId(schema);
+ if (id in refs) return id;
+
+ const base: FieldBase = {
+ description: schema.description
+ ? ctx.renderMarkdown(schema.description)
+ : undefined,
+ infoTags: generateInfoTags(schema),
+ typeName: getTypeName(schema),
+ aliasName: getTypeName(schema),
+ deprecated: schema.deprecated,
+ enumValues: schema.enum
+ ? schema.enum.map((v: unknown) => String(v))
+ : undefined,
+ };
+
+ // Handle oneOf/anyOf
+ if (schema.oneOf || schema.anyOf) {
+ const variants = schema.oneOf || schema.anyOf || [];
+ refs[id] = {
+ ...base,
+ type: 'or',
+ items: variants.map((variant: SimpleSchema) => ({
+ name: getTypeName(variant),
+ $type: processSchema(variant),
+ })),
+ };
+ return id;
+ }
+
+ // Handle allOf - merge into single object
+ if (schema.allOf) {
+ // Merge all schemas together
+ const merged: SimpleSchema = { type: 'object', properties: {}, required: [] };
+ for (const subSchema of schema.allOf) {
+ if (subSchema.properties) {
+ Object.assign(merged.properties, subSchema.properties);
+ }
+ if (subSchema.required) {
+ merged.required.push(...subSchema.required);
+ }
+ }
+ if (Object.keys(merged.properties).length > 0) {
+ const props = Object.entries(merged.properties)
+ .filter(([_, propSchema]) => isVisible(propSchema))
+ .map(([name, propSchema]) => ({
+ name,
+ $type: processSchema(propSchema),
+ required: merged.required.includes(name),
+ }));
+ refs[id] = {
+ ...base,
+ type: 'object',
+ props,
+ };
+ return id;
+ }
+ }
+
+ // Handle object
+ if ((schema.type === 'object' || schema.properties) && schema.properties) {
+ const required = schema.required || [];
+ const props = Object.entries(schema.properties)
+ .filter(([_, propSchema]) => isVisible(propSchema))
+ .map(([name, propSchema]) => ({
+ name,
+ $type: processSchema(propSchema as SimpleSchema),
+ required: required.includes(name),
+ }));
+
+ refs[id] = {
+ ...base,
+ type: 'object',
+ props,
+ };
+ return id;
+ }
+
+ // Handle array
+ if (schema.type === 'array' && schema.items) {
+ refs[id] = {
+ ...base,
+ type: 'array',
+ item: { $type: processSchema(schema.items) },
+ };
+ return id;
+ }
+
+ // Primitive type
+ refs[id] = {
+ ...base,
+ type: 'primitive',
+ };
+ return id;
+ }
+
+ function generateInfoTags(schema: SimpleSchema): ReactNode[] {
+ const tags: ReactNode[] = [];
+
+ if (schema.default !== undefined) {
+ tags.push(
+ <div key="default" className="bg-fd-secondary border rounded-lg text-xs p-1.5 shadow-md">
+ <span className="font-medium me-2">Default</span>
+ <code className="text-fd-muted-foreground">{JSON.stringify(schema.default)}</code>
+ </div>
+ );
+ }
+
+ if (schema.format) {
+ tags.push(
+ <div key="format" className="bg-fd-secondary border rounded-lg text-xs p-1.5 shadow-md">
+ <span className="font-medium me-2">Format</span>
+ <code className="text-fd-muted-foreground">{schema.format}</code>
+ </div>
+ );
+ }
+
+ // Enum values are rendered separately in the UI, not as an info tag
+
+ return tags;
+ }
+
+ const $root = processSchema(options.root);
+ return { $root, refs };
+}