@devries-cameron20 / composio Mirror · read-only / commits / 26bfd2bab
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 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 });