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: polish API reference schema rendering

Sushmithamalleshc5bc2dde4665
diff --git a/docs/app/global.css b/docs/app/global.css
index 62a2ab4f3..324843b9c 100644
--- a/docs/app/global.css
+++ b/docs/app/global.css
@@ -488,6 +488,11 @@ div.flex.items-center:has(> span.font-mono.text-fd-primary > span.text-red-400)
color: #f87171;
}
+/* Hide redundant "application/json" content type labels */
+p.text-fd-muted-foreground.not-prose:has(> code.text-xs) {
+ display: none;
+}
+
/* ==========================================================================
Table of Contents (Right Sidebar)
========================================================================== */
diff --git a/docs/components/api-page.tsx b/docs/components/api-page.tsx
index ed1e571ab..b7fc89f02 100644
--- a/docs/components/api-page.tsx
+++ b/docs/components/api-page.tsx
@@ -19,12 +19,14 @@ export const APIPage = createAPIPage(openapi, {
schema: { getRawRef: ctx.schema.getRawRef },
}
);
+ const isResponse = options.readOnly === true && !options.writeOnly;
return (
<CustomSchemaUI
name={options.client.name}
required={options.client.required}
as={options.client.as}
generated={generated}
+ isResponse={isResponse}
/>
);
},
diff --git a/docs/components/custom-schema-ui.tsx b/docs/components/custom-schema-ui.tsx
index 9202344a2..f102321d4 100644
--- a/docs/components/custom-schema-ui.tsx
+++ b/docs/components/custom-schema-ui.tsx
@@ -4,7 +4,6 @@ import {
createContext,
Fragment,
use,
- useMemo,
useState,
type ReactNode,
} from 'react';
@@ -48,9 +47,11 @@ interface SchemaUIProps {
required?: boolean;
as?: 'property' | 'body';
generated: SchemaUIGeneratedData;
+ isResponse?: boolean;
}
const DataContext = createContext<SchemaUIGeneratedData | null>(null);
+const ResponseContext = createContext(false);
function useData() {
const ctx = use(DataContext);
@@ -58,27 +59,34 @@ function useData() {
return ctx;
}
+function useIsResponse() {
+ return use(ResponseContext);
+}
+
export function CustomSchemaUI({
name,
required = false,
as = 'property',
generated,
+ isResponse = false,
}: SchemaUIProps) {
const schema = generated.refs[generated.$root];
- const isProperty = as === 'property' || !isExpandable(schema);
+ const isProperty = as === 'property' || !isExpandable(schema, generated.refs);
return (
<DataContext value={generated}>
- {isProperty ? (
- <SchemaProperty
- name={name}
- $type={generated.$root}
- required={required}
- isRoot
- />
- ) : (
- <SchemaContent $type={generated.$root} />
- )}
+ <ResponseContext value={isResponse}>
+ {isProperty ? (
+ <SchemaProperty
+ name={name}
+ $type={generated.$root}
+ required={required}
+ isRoot
+ />
+ ) : (
+ <SchemaContent $type={generated.$root} />
+ )}
+ </ResponseContext>
</DataContext>
);
}
@@ -120,7 +128,7 @@ function SchemaContent({
{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]) && (
+ {isExpandable(refs[item.$type], refs) && (
<ExpandableContent $type={item.$type} parentPath={parentPath} />
)}
</div>
@@ -146,10 +154,11 @@ function SchemaProperty({
isRoot?: boolean;
}) {
const { refs } = useData();
+ const isResponse = useIsResponse();
const schema = refs[$type];
const fullPath = parentPath ? `${parentPath}.${name}` : name;
- const hasChildren = isExpandable(schema);
+ const hasChildren = isExpandable(schema, refs);
const typeDisplay = getTypeDisplay(schema);
return (
@@ -162,7 +171,7 @@ function SchemaProperty({
<span className="text-sm font-mono text-fd-muted-foreground">
{typeDisplay}
</span>
- {required && (
+ {required && !isResponse && (
<span className="text-xs text-red-400 font-medium">Required</span>
)}
{schema.deprecated && (
@@ -235,21 +244,21 @@ function ExpandableContent({
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">
+ <CollapsibleTrigger className="group flex items-center gap-1 px-2 py-1 text-xs text-fd-muted-foreground hover:text-fd-foreground font-medium rounded border border-fd-border hover:bg-fd-accent/30 transition-colors">
{isOpen ? (
<>
- <X className="h-4 w-4" />
+ <X className="h-3 w-3" />
Hide {label}
</>
) : (
<>
- <Plus className="h-4 w-4" />
+ <Plus className="h-3 w-3" />
Show {childCount > 0 ? `${childCount} ` : ''}{label}
</>
)}
</CollapsibleTrigger>
<CollapsibleContent>
- <div className="mt-2 pl-4 border-l-2 border-fd-border">
+ <div className="mt-2 pl-3 border-l border-fd-border">
<SchemaContent $type={$type} parentPath={parentPath} />
</div>
</CollapsibleContent>
@@ -257,10 +266,24 @@ function ExpandableContent({
);
}
-function isExpandable(schema: SchemaData): boolean {
+function isExpandable(schema: SchemaData, refs?: Record<string, 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;
+ if (schema.type === 'array') {
+ // Only expandable if items have structure (object/nested)
+ if (!refs) return true;
+ const itemSchema = refs[schema.item.$type];
+ if (!itemSchema) return true;
+ return itemSchema.type !== 'primitive';
+ }
+ if ((schema.type === 'or' || schema.type === 'and') && schema.items.length > 0) {
+ // Only expandable if at least one variant has nested structure
+ if (!refs) return true;
+ return schema.items.some((item) => {
+ const itemSchema = refs[item.$type];
+ if (!itemSchema) return false;
+ return isExpandable(itemSchema, refs);
+ });
+ }
return false;
}
diff --git a/docs/components/schema-generator.tsx b/docs/components/schema-generator.tsx
index b23657cf1..14341024f 100644
--- a/docs/components/schema-generator.tsx
+++ b/docs/components/schema-generator.tsx
@@ -207,20 +207,22 @@ export function generateSchemaData(
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>
- );
+ const defaultStr = JSON.stringify(schema.default);
+ // Skip empty objects/arrays as defaults - they're noise
+ if (defaultStr !== '{}' && defaultStr !== '[]') {
+ tags.push(
+ <span key="default" className="text-xs text-fd-muted-foreground">
+ Default: <code className="rounded border border-fd-border px-1 py-0.5 font-mono">{defaultStr}</code>
+ </span>
+ );
+ }
}
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>
+ <span key="format" className="text-xs text-fd-muted-foreground">
+ Format: <code className="rounded border border-fd-border px-1 py-0.5 font-mono">{schema.format}</code>
+ </span>
);
}