@devries-cameron20 / composio-1 / commits / 00f2f45e1
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.

docs: order API endpoints by lifecycle

Brendan O'Leary committed Sep 17, 2026 at 18:38 UTC 00f2f45e1378ecb7da4318cacf69f7ad538d147d
2 files changed +63 -1
docs/lib/source.ts
+41 -1
@@ -7,7 +7,13 @@ import {
7 changelog,
8 } from 'fumadocs-mdx:collections/server';
9 import type { DocCollectionEntry } from 'fumadocs-mdx/runtime/server';
10 -import { type InferPageType, loader, multiple } from 'fumadocs-core/source';
10 +import type { Folder, Node } from 'fumadocs-core/page-tree';
11 +import {
12 + type ContentStorage,
13 + type InferPageType,
14 + loader,
15 + multiple,
16 +} from 'fumadocs-core/source';
17 import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
18 import { openapi, openapiV3 } from './openapi';
19 import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';
@@ -48,6 +54,39 @@ function loadOpenapiPages() {
54
55 type OpenapiPages = Awaited<ReturnType<typeof loadOpenapiPages>>;
56
57 +const API_METHOD_ORDER: Partial<Record<string, number>> = {
58 + post: 0, // create
59 + patch: 1, // update
60 + put: 1, // update
61 + get: 2, // read
62 + delete: 3,
63 +};
64 +
65 +const openApiPageDataSchema = z.object({
66 + _openapi: z.object({ method: z.string() }),
67 +});
68 +
69 +/** Orders generated OpenAPI siblings while leaving authored sidebar items in place. */
70 +function orderApiOperations(folder: Folder, storage: ContentStorage): Folder {
71 + const ranks = new Map<Node, number>();
72 + for (const node of folder.children) {
73 + if (node.type !== 'page' || !node.$ref) continue;
74 + const file = storage.read(node.$ref);
75 + if (!file || file.format !== 'page') continue;
76 +
77 + const parsed = openApiPageDataSchema.safeParse(file.data);
78 + if (parsed.success) ranks.set(node, API_METHOD_ORDER[parsed.data._openapi.method] ?? 4);
79 + }
80 +
81 + const ordered = [...ranks].sort((a, b) => a[1] - b[1]).map(([node]) => node);
82 + let index = 0;
83 +
84 + return {
85 + ...folder,
86 + children: folder.children.map(node => (ranks.has(node) ? ordered[index++] : node)),
87 + };
88 +}
89 +
90 // One combined reference source with both v3.1 and v3.0 OpenAPI pages.
91 // v3.1 at api-reference/, v3.0 at api-reference/v3/
92 let _openapiPagesPromise: ReturnType<typeof loadOpenapiPages> | null = null;
@@ -78,6 +117,7 @@ function createReferenceSource(openapiLatest: OpenapiPages[0], openapiV3Pages: O
117 transformers: [
118 {
119 folder(node, folderPath) {
120 + node = orderApiOperations(node, this.storage);
121 if (
122 folderPath === 'api-reference' ||
123 folderPath === 'sdk-reference' ||
docs/tests/static/api-reference-routes.test.ts
+22
@@ -30,6 +30,7 @@ import { z } from 'zod';
30 import { openapi, openapiV3 } from '../../lib/openapi';
31 import { apiEndpointsSchema } from '../../lib/api-endpoints-table-schema';
32 import { HIDDEN_API_TAGS } from '../../lib/filter-api-version';
33 +import { getReferenceSource } from '../../lib/source';
34
35 const DOCS_DIR = join(import.meta.dir, '../..');
36
@@ -134,6 +135,27 @@ async function generatedReferenceUrls(): Promise<Set<string>> {
135 const generatedUrlsPromise = generatedReferenceUrls();
136
137 describe('API reference route completeness', () => {
138 + test('sidebar operations follow create, update, read, delete order', async () => {
139 + const source = await getReferenceSource();
140 + const operationIds = source.pageTree.children
141 + .flatMap(function pages(node): string[] {
142 + if (node.type === 'page') return [node.url];
143 + if (node.type === 'folder') return node.children.flatMap(pages);
144 + return [];
145 + })
146 + .filter(url => url.startsWith('/reference/api-reference/auth-configs/'))
147 + .map(url => url.slice(url.lastIndexOf('/') + 1));
148 +
149 + expect(operationIds).toEqual([
150 + 'postAuthConfigs',
151 + 'patchAuthConfigsByNanoid',
152 + 'patchAuthConfigsByNanoidByStatus',
153 + 'getAuthConfigs',
154 + 'getAuthConfigsByNanoid',
155 + 'deleteAuthConfigsByNanoid',
156 + ]);
157 + });
158 +
159 test('every visible operation declares a tag and an operationId', () => {
160 const violations: string[] = [];
161 for (const fileName of ['openapi.json', 'openapi-v3.json', 'openapi-webhooks.json']) {