Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
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