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 21, 03:37 UTC
fix(docs): generate one overview page per webhook tag
The webhooks spec is about to carry a second tag (Session Webhooks). The index generator threw on more than one tag; it now writes an overview page for each. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Nov 18, 2026 at 18:50 UTC
26bfd2bab28e81ba4c26f839d2c033e8b072184d
3 files changed
+77
-34
docs/lib/openapi.ts
+2
-1
@@ -15,7 +15,8 @@ const openapiV3Path = join(process.cwd(), 'public/openapi-v3.json');
15
// v3.1 (latest) — clean operationIds, default API reference.
16
// The webhook-events spec (openapi-webhooks.json) is a separate OpenAPI 3.1
17
// document whose top-level `webhooks` block documents the payloads Composio
18
-// delivers to customer webhook URLs; it renders under the "Webhook Events" tag.
18
+// delivers to customer webhook URLs; each of its tags (e.g. "Webhook Events")
19
+// renders as its own section.
20
export const openapi = createOpenAPI({
21
input: {
22
[openapiPath]: () => loadOpenAPISchema(openapiPath),
docs/scripts/generate-api-index.ts
+45
-33
@@ -144,9 +144,9 @@ function loadWebhookSpec(): WebhookSpec | null {
144
/**
145
* Tag slugs contributed by the separate webhook-events spec (PLEN-2793). Its
146
* operations live under the OpenAPI 3.1 `webhooks` block (not `paths`) and its
147
- * tag ("Webhook Events") is absent from openapi.json — so without folding these
148
- * into the active set, `removeStaleTagIndexes` would recursively delete the
149
- * hand-authored `webhook-events` overview folder on the next docs data run.
147
+ * tags (e.g. "Webhook Events") are absent from openapi.json — so without folding
148
+ * these into the active set, `removeStaleTagIndexes` would recursively delete
149
+ * their generated overview folders on the next docs data run.
150
*/
151
function webhookTagSlugs(spec: WebhookSpec | null): Set<string> {
152
const slugs = new Set<string>();
@@ -162,46 +162,57 @@ function webhookTagSlugs(spec: WebhookSpec | null): Set<string> {
162
return slugs;
163
}
164
165
+type WebhookEntry = [eventKey: string, operation: OpenAPIOperation];
166
+
167
/**
166
- * Generates the Webhook Events overview page from the webhooks spec.
168
+ * Generates one overview page per webhook tag. The webhooks spec can group its
169
+ * events under several tags (e.g. Webhook Events and Session Webhooks), and
170
+ * Fumadocs files each event page under its tag, so each tag gets its own index.
171
*
172
* The event list MUST be derived, not hand-maintained: adding an event to the
173
* Apollo registry would otherwise leave it off this page, and removing one would
174
* leave a link to a page Fumadocs no longer builds (a 404). Prose lives in
171
- * `api-overviews/webhook-events.mdx`; everything below it is generated.
175
+ * `api-overviews/<tagSlug>.mdx`; everything below it is generated.
176
*
177
* Individual event pages are rendered by Fumadocs straight from the spec, so
174
- * this page only needs the index tables.
178
+ * these pages only need the index tables.
179
*/
176
-function generateWebhookEventsIndex(spec: WebhookSpec | null, outputDir: string) {
180
+function generateWebhookIndexes(spec: WebhookSpec | null, outputDir: string) {
181
if (!spec) return;
182
179
- const entries = Object.entries(spec.webhooks ?? {});
180
- if (entries.length === 0) return;
183
+ const entriesByTag = new Map<string, WebhookEntry[]>();
184
+ for (const [key, item] of Object.entries(spec.webhooks ?? {})) {
185
+ const operation = item.post;
186
+ if (!operation?.operationId) continue;
187
182
- const operationTags = new Set(
183
- entries.flatMap(([, item]) => item.post?.tags ?? []),
184
- );
185
- if (operationTags.size !== 1) {
186
- throw new Error(
187
- `Expected webhook operations to share exactly one tag, found: ${[...operationTags].join(', ') || 'none'}`,
188
- );
188
+ const tags = operation.tags ?? [];
189
+ if (tags.length === 0) {
190
+ throw new Error(`Webhook operation "${key}" has no tag`);
191
+ }
192
+ for (const tagName of tags) {
193
+ entriesByTag.set(tagName, [...(entriesByTag.get(tagName) ?? []), [key, operation]]);
194
+ }
195
}
196
191
- const [operationTag] = operationTags;
192
- const tag = spec.tags?.find(candidate => candidate.name === operationTag);
193
- if (!tag) {
194
- throw new Error(`Webhook operation tag "${operationTag}" is not declared in spec.tags`);
197
+ for (const [tagName, entries] of entriesByTag) {
198
+ const tag = spec.tags?.find(candidate => candidate.name === tagName);
199
+ if (!tag) {
200
+ throw new Error(`Webhook operation tag "${tagName}" is not declared in spec.tags`);
201
+ }
202
+ generateWebhookTagIndex(tag, entries, outputDir);
203
}
196
- const tagSlug = slugify(tag.name);
204
+}
205
206
+function generateWebhookTagIndex(
207
+ tag: { name: string; description?: string },
208
+ entries: WebhookEntry[],
209
+ outputDir: string,
210
+) {
211
+ const tagSlug = slugify(tag.name);
212
const current: string[] = [];
213
const legacy: string[] = [];
214
201
- for (const [key, item] of entries) {
202
- const operation = item.post;
203
- if (!operation?.operationId) continue;
204
-
215
+ for (const [key, operation] of entries) {
216
const href = `/reference/api-reference/${tagSlug}/${operation.operationId}`;
217
const label = operation.summary ?? key;
218
@@ -221,7 +232,7 @@ function generateWebhookEventsIndex(spec: WebhookSpec | null, outputDir: string)
232
}
233
234
const overview = readOverview(tagSlug);
224
- const body = overview ?? tag?.description ?? '';
235
+ const body = overview ?? tag.description ?? '';
236
237
const legacySection =
238
legacy.length > 0
@@ -237,8 +248,8 @@ ${legacy.join('\n')}`
248
: '';
249
250
const content = `---
240
-title: ${tag?.name ?? 'Webhook Events'}
241
-description: "${tag?.description ?? ''}"
251
+title: ${tag.name}
252
+description: "${tag.description ?? ''}"
253
---
254
255
{/* Auto-generated from openapi-webhooks.json. Edit the overview at api-overviews/${tagSlug}.mdx, not this file. */}
@@ -296,10 +307,11 @@ function generateIndexPages() {
307
const outputDir = join(process.cwd(), 'content/reference/api-reference');
308
const webhookSpec = loadWebhookSpec();
309
299
- // `Webhook Events` is tagged only in openapi-webhooks.json, so it never appears
300
- // in the openapi.json-derived active set. Without folding it in, the section is
301
- // recursively deleted on every run (and immediately regenerated below) — and if
302
- // that ordering ever changed, the docs would silently lose the whole section.
310
+ // Webhook tags (e.g. `Webhook Events`) are used only in openapi-webhooks.json,
311
+ // so they never appear in the openapi.json-derived active set. Without folding
312
+ // them in, their sections are recursively deleted on every run (and immediately
313
+ // regenerated below) — and if that ordering ever changed, the docs would
314
+ // silently lose those sections.
315
removeStaleTagIndexes(
316
outputDir,
317
new Set([...activeTagSlugs(v31Ops), ...webhookTagSlugs(webhookSpec)]),
@@ -311,7 +323,7 @@ function generateIndexPages() {
323
324
// Webhook events come from a separate 3.1 spec, so they're generated here
325
// rather than in the tag loop below (which iterates openapi.json operations).
314
- generateWebhookEventsIndex(webhookSpec, outputDir);
326
+ generateWebhookIndexes(webhookSpec, outputDir);
327
328
// Get all unique tag names
329
const allTags = new Set([...Object.keys(v31Ops), ...Object.keys(v3Ops)]);
docs/tests/static/api-deprecation.test.tsx
+30
@@ -442,4 +442,34 @@ describe("webhook API index", () => {
442
).exists(),
443
).toBe(false);
444
});
445
+
446
+ test("generates one index per webhook tag, each listing only its own events", async () => {
447
+ const webhookSpec = createWebhookSpec();
448
+ webhookSpec.tags.push({ name: "Session Webhooks", description: "Session webhook requests" });
449
+ Object.assign(webhookSpec.webhooks, {
450
+ "composio.session_hook.before_execute": {
451
+ post: {
452
+ tags: ["Session Webhooks"],
453
+ summary: "Before execute",
454
+ operationId: "composio_session_hook_before_execute",
455
+ },
456
+ },
457
+ });
458
+ const fixtureDir = await generateFixture({ webhookSpec });
459
+ const readIndex = (tagSlug: string) =>
460
+ readFile(join(fixtureDir, `content/reference/api-reference/${tagSlug}/index.mdx`), "utf-8");
461
+
462
+ const webhookEvents = await readIndex("webhook-events");
463
+ expect(webhookEvents).toContain(
464
+ "[Test event](/reference/api-reference/webhook-events/composio_test_event)",
465
+ );
466
+ expect(webhookEvents).not.toContain("composio_session_hook_before_execute");
467
+
468
+ const sessionWebhooks = await readIndex("session-webhooks");
469
+ expect(sessionWebhooks).toContain("title: Session Webhooks");
470
+ expect(sessionWebhooks).toContain(
471
+ "[Before execute](/reference/api-reference/session-webhooks/composio_session_hook_before_execute)",
472
+ );
473
+ expect(sessionWebhooks).not.toContain("composio_test_event");
474
+ });
475
});