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, 12:15 UTC
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']) {