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
feat(docs): rewrite API reference markdown using fumadocs-openapi
Sushmithamallesha1ffb0d55978
diff --git a/docs/app/llms.mdx/[[...slug]]/route.ts b/docs/app/llms.mdx/[[...slug]]/route.tsindex 99bdaf50a..3896061f3 100644--- a/docs/app/llms.mdx/[[...slug]]/route.ts+++ b/docs/app/llms.mdx/[[...slug]]/route.ts@@ -6,6 +6,7 @@ import {toolkitsSource,getLLMText,} from '@/lib/source';+import { openapi } from '@/lib/openapi';import { notFound } from 'next/navigation';import { readFile } from 'fs/promises';import { join } from 'path';@@ -13,21 +14,63 @@ import type { Toolkit } from '@/types/toolkit';export const revalidate = false;-// OpenAPI spec cache-let openapiSpecCache: Record<string, unknown> | null = null;+// Types for OpenAPI structures (from dereferenced document)+interface OpenAPISchema {+ type?: string;+ format?: string;+ description?: string;+ properties?: Record<string, OpenAPISchema>;+ items?: OpenAPISchema;+ required?: string[];+ enum?: string[];+ oneOf?: OpenAPISchema[];+ anyOf?: OpenAPISchema[];+ allOf?: OpenAPISchema[];+ default?: unknown;+ example?: unknown;+ minimum?: number;+ maximum?: number;+ minLength?: number;+ maxLength?: number;+}-async function getOpenAPISpec(): Promise<Record<string, unknown>> {- if (openapiSpecCache) return openapiSpecCache;- const filePath = join(process.cwd(), 'public/openapi.json');- const data = await readFile(filePath, 'utf-8');- const spec = JSON.parse(data) as Record<string, unknown>;- openapiSpecCache = spec;- return spec;+interface OpenAPIParameter {+ name: string;+ in: 'query' | 'path' | 'header' | 'cookie';+ description?: string;+ required?: boolean;+ schema?: OpenAPISchema;+ example?: unknown;+}++interface OpenAPIRequestBody {+ description?: string;+ required?: boolean;+ content?: Record<string, { schema?: OpenAPISchema; example?: unknown }>;+}++interface OpenAPIResponse {+ description?: string;+ content?: Record<string, { schema?: OpenAPISchema; example?: unknown }>;+}++interface OpenAPISecurityScheme {+ type: string;+ description?: string;+ name?: string;+ in?: string;+ scheme?: string;+ bearerFormat?: string;}interface OpenAPIOperation {- method: string;- path: string;+ summary?: string;+ description?: string;+ operationId?: string;+ parameters?: OpenAPIParameter[];+ requestBody?: OpenAPIRequestBody;+ responses?: Record<string, OpenAPIResponse>;+ security?: Array<Record<string, string[]>>;tags?: string[];}@@ -36,42 +79,93 @@ interface OpenAPIPageData {description?: string;getAPIPageProps: () => {document: string;- operations?: OpenAPIOperation[];- webhooks?: { name: string; method: string }[];+ operations?: Array<{ method: string; path: string; tags?: string[] }>;+ webhooks?: Array<{ name: string; method: string }>;};}-// Helper to render JSON schema properties as markdown-function renderSchemaProperties(- schema: Record<string, unknown>,- indent = 0-): string[] {+// Generate sample value for a schema+function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {+ if (depth > 3) return '...'; // Prevent infinite recursion++ if (schema.example !== undefined) return schema.example;+ if (schema.default !== undefined) return schema.default;+ if (schema.enum && schema.enum.length > 0) return schema.enum[0];++ switch (schema.type) {+ case 'string':+ if (schema.format === 'email') return '[email protected]';+ if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com';+ if (schema.format === 'date') return '2024-01-15';+ if (schema.format === 'date-time') return '2024-01-15T10:30:00Z';+ if (schema.format === 'uuid') return '550e8400-e29b-41d4-a716-446655440000';+ return 'string';+ case 'integer':+ case 'number':+ return schema.minimum ?? 1;+ case 'boolean':+ return true;+ case 'array':+ if (schema.items) {+ return [generateSampleValue(schema.items, depth + 1)];+ }+ return [];+ case 'object':+ if (schema.properties) {+ const obj: Record<string, unknown> = {};+ for (const [key, prop] of Object.entries(schema.properties)) {+ obj[key] = generateSampleValue(prop, depth + 1);+ }+ return obj;+ }+ return {};+ default:+ return null;+ }+}++// Render schema as markdown with proper nesting+function renderSchema(schema: OpenAPISchema, indent = 0, maxDepth = 4): string[] {+ if (indent > maxDepth) return [' '.repeat(indent) + '- ...'];+const lines: string[] = [];const prefix = ' '.repeat(indent);+ const required = schema.required || [];if (schema.type === 'object' && schema.properties) {- const props = schema.properties as Record<string, Record<string, unknown>>;- const required = (schema.required as string[]) || [];-- for (const [name, prop] of Object.entries(props)) {+ for (const [name, prop] of Object.entries(schema.properties)) {const isRequired = required.includes(name);- const type = (prop.type as string) || 'any';- const desc = (prop.description as string) || '';- const reqMark = isRequired ? ' **(required)**' : '';+ const reqMark = isRequired ? ' *(required)*' : '';+ const typeStr = getTypeString(prop);+ const desc = prop.description ? `: ${prop.description}` : '';- lines.push(`${prefix}- \`${name}\` (${type})${reqMark}: ${desc}`);+ lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}`);- // Recurse for nested objects+ // Recurse for nested objects/arraysif (prop.type === 'object' && prop.properties) {- lines.push(...renderSchemaProperties(prop, indent + 1));+ lines.push(...renderSchema(prop, indent + 1, maxDepth));+ } else if (prop.type === 'array' && prop.items?.type === 'object' && prop.items.properties) {+ lines.push(`${prefix} - Array items:`);+ lines.push(...renderSchema(prop.items, indent + 2, maxDepth));}}} else if (schema.oneOf || schema.anyOf) {- const variants = (schema.oneOf || schema.anyOf) as Record<string, unknown>[];- lines.push(`${prefix}One of the following:`);+ const variants = schema.oneOf || schema.anyOf || [];+ lines.push(`${prefix}*One of:*`);for (const variant of variants.slice(0, 3)) {- if (variant.type === 'object') {- lines.push(...renderSchemaProperties(variant, indent + 1));+ if (variant.type === 'object' && variant.properties) {+ lines.push(...renderSchema(variant, indent + 1, maxDepth));+ } else {+ lines.push(`${prefix} - ${getTypeString(variant)}`);+ }+ }+ if (variants.length > 3) {+ lines.push(`${prefix} - ... and ${variants.length - 3} more`);+ }+ } else if (schema.allOf) {+ for (const part of schema.allOf) {+ if (part.type === 'object' && part.properties) {+ lines.push(...renderSchema(part, indent, maxDepth));}}}@@ -79,36 +173,77 @@ function renderSchemaProperties(return lines;}-// Generate cURL example-function generateCurlExample(+// Get a readable type string+function getTypeString(schema: OpenAPISchema): string {+ if (schema.enum) {+ return `enum: ${schema.enum.slice(0, 3).map(e => `"${e}"`).join(' | ')}${schema.enum.length > 3 ? ' | ...' : ''}`;+ }+ if (schema.type === 'array' && schema.items) {+ return `array<${getTypeString(schema.items)}>`;+ }+ if (schema.format) {+ return `${schema.type} (${schema.format})`;+ }+ return schema.type || 'any';+}++// Generate cURL example with sample data+function generateCurl(method: string,path: string,baseUrl: string,- hasBody: boolean+ parameters: OpenAPIParameter[] = [],+ requestBody?: OpenAPIRequestBody): string {- const pathWithExample = path.replace(/\{(\w+)\}/g, 'example_$1');- let curl = `curl -X ${method.toUpperCase()} "${baseUrl}${pathWithExample}"`;+ // Build path with sample values+ let url = path;+ const queryParams: string[] = [];++ for (const param of parameters) {+ const sample = param.example ?? generateSampleValue(param.schema || { type: 'string' });+ if (param.in === 'path') {+ url = url.replace(`{${param.name}}`, String(sample));+ } else if (param.in === 'query' && param.required) {+ queryParams.push(`${param.name}=${encodeURIComponent(String(sample))}`);+ }+ }++ if (queryParams.length > 0) {+ url += '?' + queryParams.join('&');+ }++ let curl = `curl -X ${method.toUpperCase()} "${baseUrl}${url}"`;curl += ` \\\n -H "x-api-key: YOUR_API_KEY"`;- if (hasBody) {++ // Add request body+ if (requestBody?.content?.['application/json']) {curl += ` \\\n -H "Content-Type: application/json"`;- curl += ` \\\n -d '{}'`;+ const schema = requestBody.content['application/json'].schema;+ const example = requestBody.content['application/json'].example;+ const body = example ?? (schema ? generateSampleValue(schema) : {});+ curl += ` \\\n -d '${JSON.stringify(body, null, 2).split('\n').join('\n ')}'`;}+return curl;}-// Convert OpenAPI page to markdown+// Convert OpenAPI page to comprehensive markdownasync function openapiPageToMarkdown(page: { url: string; data: OpenAPIPageData }): Promise<string> {const { title, description } = page.data;const props = page.data.getAPIPageProps();- const spec = await getOpenAPISpec();- const paths = spec.paths as Record<string, Record<string, unknown>> | undefined;- const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as Record<string, Record<string, unknown>> | undefined;++ // Get fully dereferenced document from fumadocs-openapi+ const processed = await openapi.getSchema(props.document);+ const spec = processed.dereferenced;+ const paths = spec.paths as Record<string, Record<string, OpenAPIOperation>> | undefined;+ const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as Record<string, OpenAPISecurityScheme> | undefined;const servers = spec.servers as Array<{ url: string; description?: string }> | undefined;const baseUrl = servers?.[0]?.url || 'https://backend.composio.dev';- const lines: string[] = [`# ${title} (${page.url})`, ''];+ const lines: string[] = [`# ${title}`, ''];+ lines.push(`**Documentation:** ${page.url}`, '');if (description) {lines.push(description, '');@@ -120,123 +255,119 @@ async function openapiPageToMarkdown(const pathData = paths[op.path];if (!pathData) continue;- const methodData = pathData[op.method] as Record<string, unknown> | undefined;- if (!methodData) continue;+ const operation = pathData[op.method];+ if (!operation) continue;- lines.push(`## ${(op.method as string).toUpperCase()} ${op.path}`, '');- lines.push(`**Base URL:** \`${baseUrl}\``, '');+ lines.push('---', '');+ lines.push(`## ${op.method.toUpperCase()} \`${op.path}\``, '');+ lines.push(`**Endpoint:** \`${baseUrl}${op.path}\``, '');- if (methodData.summary) {- lines.push(`${methodData.summary}`, '');+ if (operation.summary) {+ lines.push(`**Summary:** ${operation.summary}`, '');}- if (methodData.description) {- lines.push(`${methodData.description}`, '');+ if (operation.description) {+ lines.push(operation.description, '');}// Authentication- const security = methodData.security as Array<Record<string, string[]>> | undefined;+ const security = operation.security;if (security && security.length > 0 && securitySchemes) {lines.push('### Authentication', '');+ const authMethods: string[] = [];for (const secReq of security) {for (const schemeName of Object.keys(secReq)) {const scheme = securitySchemes[schemeName];if (scheme) {- const inLoc = scheme.in as string;- const headerName = scheme.name as string;- const schemeDesc = scheme.description as string;- lines.push(`- **${schemeName}**: ${schemeDesc || ''}`);- lines.push(` - Type: \`${scheme.type}\``);- lines.push(` - In: \`${inLoc}\``);- lines.push(` - Header: \`${headerName}\``);+ if (scheme.type === 'apiKey') {+ authMethods.push(`**${schemeName}** - API Key in \`${scheme.in}\` header \`${scheme.name}\``);+ } else if (scheme.type === 'http' && scheme.scheme === 'bearer') {+ authMethods.push(`**${schemeName}** - Bearer token in Authorization header`);+ } else {+ authMethods.push(`**${schemeName}** - ${scheme.type}`);+ }}}}- lines.push('');+ lines.push(authMethods.join(' OR '), '');}- // Parameters- const parameters = methodData.parameters as Array<{- name: string;- in: string;- description?: string;- required?: boolean;- schema?: { type?: string; format?: string; default?: unknown };- }> | undefined;-- if (parameters && parameters.length > 0) {- lines.push('### Parameters', '');- lines.push('| Name | In | Required | Type | Description |');- lines.push('|------|-----|----------|------|-------------|');- for (const param of parameters) {- const type = param.schema?.type || 'string';- const format = param.schema?.format ? ` (${param.schema.format})` : '';- const required = param.required ? 'Yes' : 'No';- const desc = (param.description || '').replace(/\|/g, '\\|').replace(/\n/g, ' ');- lines.push(`| ${param.name} | ${param.in} | ${required} | ${type}${format} | ${desc} |`);+ // Path Parameters+ const pathParams = operation.parameters?.filter(p => p.in === 'path') || [];+ if (pathParams.length > 0) {+ lines.push('### Path Parameters', '');+ for (const param of pathParams) {+ const typeStr = getTypeString(param.schema || { type: 'string' });+ lines.push(`- \`${param.name}\` (${typeStr}) *(required)*: ${param.description || ''}`);}lines.push('');}- // Request body- const requestBody = methodData.requestBody as {- description?: string;- required?: boolean;- content?: Record<string, { schema?: Record<string, unknown> }>;- } | undefined;+ // Query Parameters+ const queryParams = operation.parameters?.filter(p => p.in === 'query') || [];+ if (queryParams.length > 0) {+ lines.push('### Query Parameters', '');+ for (const param of queryParams) {+ const typeStr = getTypeString(param.schema || { type: 'string' });+ const reqMark = param.required ? ' *(required)*' : '';+ lines.push(`- \`${param.name}\` (${typeStr})${reqMark}: ${param.description || ''}`);+ }+ lines.push('');+ }- if (requestBody?.content) {+ // Request Body+ if (operation.requestBody?.content?.['application/json']) {lines.push('### Request Body', '');- if (requestBody.description) {- lines.push(requestBody.description, '');+ if (operation.requestBody.description) {+ lines.push(operation.requestBody.description, '');}- const jsonContent = requestBody.content['application/json'];- if (jsonContent?.schema) {- const schemaProps = renderSchemaProperties(jsonContent.schema);- if (schemaProps.length > 0) {- lines.push('**Properties:**', '');- lines.push(...schemaProps);- lines.push('');- }+ const schema = operation.requestBody.content['application/json'].schema;+ if (schema) {+ lines.push('**Schema:**', '');+ lines.push(...renderSchema(schema));+ lines.push('');++ // Example+ const example = operation.requestBody.content['application/json'].example ?? generateSampleValue(schema);+ lines.push('**Example:**', '');+ lines.push('```json');+ lines.push(JSON.stringify(example, null, 2));+ lines.push('```', '');}}// Responses- const responses = methodData.responses as Record<string, {- description?: string;- content?: Record<string, { schema?: Record<string, unknown> }>;- }> | undefined;-- if (responses) {- // Response status codes table+ if (operation.responses) {lines.push('### Responses', '');- lines.push('| Status | Description |');- lines.push('|--------|-------------|');- for (const [status, response] of Object.entries(responses)) {- const desc = (response.description || '').replace(/\|/g, '\\|').replace(/\n/g, ' ');- lines.push(`| ${status} | ${desc} |`);- }- lines.push('');- // Success response body (2xx only)- for (const [status, response] of Object.entries(responses)) {- if (!status.startsWith('2')) continue;+ for (const [status, response] of Object.entries(operation.responses)) {+ const statusEmoji = status.startsWith('2') ? '✅' : status.startsWith('4') ? '⚠️' : '❌';+ lines.push(`#### ${statusEmoji} ${status} - ${response.description || ''}`, '');+const jsonContent = response.content?.['application/json'];if (jsonContent?.schema) {- const schemaProps = renderSchemaProperties(jsonContent.schema);- if (schemaProps.length > 0) {- lines.push(`### Response Body (${status})`, '');- lines.push(...schemaProps);- lines.push('');+ lines.push('**Response Schema:**', '');+ lines.push(...renderSchema(jsonContent.schema));+ lines.push('');++ // Only show example for success responses+ if (status.startsWith('2')) {+ const example = jsonContent.example ?? generateSampleValue(jsonContent.schema);+ if (example && Object.keys(example as object).length > 0) {+ lines.push('**Example Response:**', '');+ lines.push('```json');+ lines.push(JSON.stringify(example, null, 2));+ lines.push('```', '');+ }}}}}- // cURL example- lines.push('### Example Request', '');+ // cURL Example+ lines.push('### Example cURL Request', '');lines.push('```bash');- lines.push(generateCurlExample(op.method, op.path, baseUrl, !!requestBody?.content));+ lines.push(generateCurl(op.method, op.path, baseUrl, operation.parameters, operation.requestBody));lines.push('```', '');}}