@devries-cameron20 / composio Mirror · read-only / commits / fa6cb6a1c
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 14:30 UTC

fix(docs): enhance API reference markdown with full details

API reference .md endpoints now include: - Authentication details (scheme type, header name) - Request body properties with types and descriptions - Response body schemas with nested properties - cURL example with proper headers Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Jan 19, 2026 at 17:11 UTC fa6cb6a1c4407217deef588d31adfdfcc88da4bb
1 file changed +112 -10
docs/app/llms.mdx/[[...slug]]/route.ts
+112 -10
@@ -41,6 +41,61 @@ interface OpenAPIPageData {
41 };
42 }
43
44 +// Helper to render JSON schema properties as markdown
45 +function renderSchemaProperties(
46 + schema: Record<string, unknown>,
47 + indent = 0
48 +): string[] {
49 + const lines: string[] = [];
50 + const prefix = ' '.repeat(indent);
51 +
52 + if (schema.type === 'object' && schema.properties) {
53 + const props = schema.properties as Record<string, Record<string, unknown>>;
54 + const required = (schema.required as string[]) || [];
55 +
56 + for (const [name, prop] of Object.entries(props)) {
57 + const isRequired = required.includes(name);
58 + const type = (prop.type as string) || 'any';
59 + const desc = (prop.description as string) || '';
60 + const reqMark = isRequired ? ' **(required)**' : '';
61 +
62 + lines.push(`${prefix}- \`${name}\` (${type})${reqMark}: ${desc}`);
63 +
64 + // Recurse for nested objects
65 + if (prop.type === 'object' && prop.properties) {
66 + lines.push(...renderSchemaProperties(prop, indent + 1));
67 + }
68 + }
69 + } else if (schema.oneOf || schema.anyOf) {
70 + const variants = (schema.oneOf || schema.anyOf) as Record<string, unknown>[];
71 + lines.push(`${prefix}One of the following:`);
72 + for (const variant of variants.slice(0, 3)) {
73 + if (variant.type === 'object') {
74 + lines.push(...renderSchemaProperties(variant, indent + 1));
75 + }
76 + }
77 + }
78 +
79 + return lines;
80 +}
81 +
82 +// Generate cURL example
83 +function generateCurlExample(
84 + method: string,
85 + path: string,
86 + baseUrl: string,
87 + hasBody: boolean
88 +): string {
89 + const pathWithExample = path.replace(/\{(\w+)\}/g, 'example_$1');
90 + let curl = `curl -X ${method.toUpperCase()} "${baseUrl}${pathWithExample}"`;
91 + curl += ` \\\n -H "x-api-key: YOUR_API_KEY"`;
92 + if (hasBody) {
93 + curl += ` \\\n -H "Content-Type: application/json"`;
94 + curl += ` \\\n -d '{}'`;
95 + }
96 + return curl;
97 +}
98 +
99 // Convert OpenAPI page to markdown
100 async function openapiPageToMarkdown(
101 page: { url: string; data: OpenAPIPageData }
@@ -49,6 +104,9 @@ async function openapiPageToMarkdown(
104 const props = page.data.getAPIPageProps();
105 const spec = await getOpenAPISpec();
106 const paths = spec.paths as Record<string, Record<string, unknown>> | undefined;
107 + const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as Record<string, Record<string, unknown>> | undefined;
108 + const servers = spec.servers as Array<{ url: string; description?: string }> | undefined;
109 + const baseUrl = servers?.[0]?.url || 'https://backend.composio.dev';
110
111 const lines: string[] = [`# ${title} (${page.url})`, ''];
112
@@ -66,6 +124,7 @@ async function openapiPageToMarkdown(
124 if (!methodData) continue;
125
126 lines.push(`## ${(op.method as string).toUpperCase()} ${op.path}`, '');
127 + lines.push(`**Base URL:** \`${baseUrl}\``, '');
128
129 if (methodData.summary) {
130 lines.push(`${methodData.summary}`, '');
@@ -75,13 +134,34 @@ async function openapiPageToMarkdown(
134 lines.push(`${methodData.description}`, '');
135 }
136
137 + // Authentication
138 + const security = methodData.security as Array<Record<string, string[]>> | undefined;
139 + if (security && security.length > 0 && securitySchemes) {
140 + lines.push('### Authentication', '');
141 + for (const secReq of security) {
142 + for (const schemeName of Object.keys(secReq)) {
143 + const scheme = securitySchemes[schemeName];
144 + if (scheme) {
145 + const inLoc = scheme.in as string;
146 + const headerName = scheme.name as string;
147 + const schemeDesc = scheme.description as string;
148 + lines.push(`- **${schemeName}**: ${schemeDesc || ''}`);
149 + lines.push(` - Type: \`${scheme.type}\``);
150 + lines.push(` - In: \`${inLoc}\``);
151 + lines.push(` - Header: \`${headerName}\``);
152 + }
153 + }
154 + }
155 + lines.push('');
156 + }
157 +
158 // Parameters
159 const parameters = methodData.parameters as Array<{
160 name: string;
161 in: string;
162 description?: string;
163 required?: boolean;
84 - schema?: { type?: string };
164 + schema?: { type?: string; format?: string; default?: unknown };
165 }> | undefined;
166
167 if (parameters && parameters.length > 0) {
@@ -90,9 +170,10 @@ async function openapiPageToMarkdown(
170 lines.push('|------|-----|----------|------|-------------|');
171 for (const param of parameters) {
172 const type = param.schema?.type || 'string';
173 + const format = param.schema?.format ? ` (${param.schema.format})` : '';
174 const required = param.required ? 'Yes' : 'No';
175 const desc = (param.description || '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
95 - lines.push(`| ${param.name} | ${param.in} | ${required} | ${type} | ${desc} |`);
176 + lines.push(`| ${param.name} | ${param.in} | ${required} | ${type}${format} | ${desc} |`);
177 }
178 lines.push('');
179 }
@@ -101,7 +182,7 @@ async function openapiPageToMarkdown(
182 const requestBody = methodData.requestBody as {
183 description?: string;
184 required?: boolean;
104 - content?: Record<string, { schema?: unknown }>;
185 + content?: Record<string, { schema?: Record<string, unknown> }>;
186 } | undefined;
187
188 if (requestBody?.content) {
@@ -109,25 +190,46 @@ async function openapiPageToMarkdown(
190 if (requestBody.description) {
191 lines.push(requestBody.description, '');
192 }
112 - const contentTypes = Object.keys(requestBody.content);
113 - lines.push(`Content types: ${contentTypes.join(', ')}`, '');
193 + const jsonContent = requestBody.content['application/json'];
194 + if (jsonContent?.schema) {
195 + const schemaProps = renderSchemaProperties(jsonContent.schema);
196 + if (schemaProps.length > 0) {
197 + lines.push('**Properties:**', '');
198 + lines.push(...schemaProps);
199 + lines.push('');
200 + }
201 + }
202 }
203
204 // Responses
205 const responses = methodData.responses as Record<string, {
206 description?: string;
207 + content?: Record<string, { schema?: Record<string, unknown> }>;
208 }> | undefined;
209
210 if (responses) {
211 lines.push('### Responses', '');
123 - lines.push('| Status | Description |');
124 - lines.push('|--------|-------------|');
212 for (const [status, response] of Object.entries(responses)) {
126 - const desc = (response.description || '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
127 - lines.push(`| ${status} | ${desc} |`);
213 + const desc = response.description || '';
214 + lines.push(`#### ${status} - ${desc}`, '');
215 +
216 + const jsonContent = response.content?.['application/json'];
217 + if (jsonContent?.schema) {
218 + const schemaProps = renderSchemaProperties(jsonContent.schema);
219 + if (schemaProps.length > 0) {
220 + lines.push('**Response body:**', '');
221 + lines.push(...schemaProps);
222 + lines.push('');
223 + }
224 + }
225 }
129 - lines.push('');
226 }
227 +
228 + // cURL example
229 + lines.push('### Example Request', '');
230 + lines.push('```bash');
231 + lines.push(generateCurlExample(op.method, op.path, baseUrl, !!requestBody?.content));
232 + lines.push('```', '');
233 }
234 }
235