Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add Stripe-style inline schema expansion for API reference
Sushmithamallesh22c4197fd97a
diff --git a/docs/components/api-page.tsx b/docs/components/api-page.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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 };+}