Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | /** |
| 2 | * API reference route guards. |
| 3 | * |
| 4 | * Up to 11.3, fumadocs-openapi's tag grouping silently dropped any operation |
| 5 | * whose tag was not declared in the document's top-level `tags` array |
| 6 | * (preset-auto: `builder.fromTagName(tag)` returned undefined -> `continue`, |
| 7 | * no warning). The v10 -> v11 upgrade shipped exactly that: 16 operation pages |
| 8 | * vanished from the site, sitemap, and search while the checked-in tag landing |
| 9 | * pages kept rendering quick links that 404ed. 11.4 fixed the drop, so these |
| 10 | * guards now stand as regression tripwires — the loss has already reappeared |
| 11 | * once, on a routine upgrade. Nothing else can catch this class: |
| 12 | * validate-links only sees markdown links (ApiEndpointsTable hrefs live in a |
| 13 | * JSX prop), and the integration suite samples fixed routes. |
| 14 | * |
| 15 | * Two guards, both derived from the shipped specs rather than snapshots so |
| 16 | * routine spec syncs (docs-update-data) never churn them: |
| 17 | * 1. Completeness — every operation/webhook a spec implies maps 1:1 to a page |
| 18 | * the production loader path actually generates, regardless of the drop |
| 19 | * mechanism. |
| 20 | * 2. Quick links — every href serialized into an ApiEndpointsTable in |
| 21 | * content/reference resolves to a generated page. |
| 22 | */ |
| 23 | import { describe, expect, test } from 'bun:test'; |
| 24 | import { readFileSync, readdirSync } from 'node:fs'; |
| 25 | import { join, relative } from 'node:path'; |
| 26 | import { loader, multiple } from 'fumadocs-core/source'; |
| 27 | import { createOpenAPI, openapiSource } from 'fumadocs-openapi/server'; |
| 28 | import { z } from 'zod'; |
| 29 | |
| 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 | |
| 37 | const HTTP_METHODS = [ |
| 38 | 'get', |
| 39 | 'put', |
| 40 | 'post', |
| 41 | 'delete', |
| 42 | 'options', |
| 43 | 'head', |
| 44 | 'patch', |
| 45 | 'trace', |
| 46 | ] as const; |
| 47 | |
| 48 | interface SpecOperation { |
| 49 | operationId?: string; |
| 50 | tags?: string[]; |
| 51 | } |
| 52 | |
| 53 | interface SpecDocument { |
| 54 | paths?: Record<string, Record<string, unknown>>; |
| 55 | webhooks?: Record<string, Record<string, unknown>>; |
| 56 | } |
| 57 | |
| 58 | /** Mirrors the default slugify in fumadocs-openapi's auto preset. */ |
| 59 | function slugifyTag(tag: string): string { |
| 60 | return tag.replace(/\s+/g, '-').toLowerCase(); |
| 61 | } |
| 62 | |
| 63 | /** Mirrors the hidden-tag URL filter applied in lib/source.ts. */ |
| 64 | function isHiddenReferenceUrl(url: string): boolean { |
| 65 | for (const tag of HIDDEN_API_TAGS) { |
| 66 | if ( |
| 67 | url.startsWith(`/reference/api-reference/${tag}/`) || |
| 68 | url.startsWith(`/reference/v3/api-reference/${tag}/`) |
| 69 | ) { |
| 70 | return true; |
| 71 | } |
| 72 | } |
| 73 | return false; |
| 74 | } |
| 75 | |
| 76 | function* specOperations(document: SpecDocument): Generator<{ |
| 77 | location: string; |
| 78 | operation: SpecOperation; |
| 79 | }> { |
| 80 | for (const group of [document.paths, document.webhooks]) { |
| 81 | for (const [key, pathItem] of Object.entries(group ?? {})) { |
| 82 | for (const method of HTTP_METHODS) { |
| 83 | const operation = pathItem?.[method]; |
| 84 | if (!operation || typeof operation !== 'object') continue; |
| 85 | yield { location: `${method.toUpperCase()} ${key}`, operation }; |
| 86 | } |
| 87 | } |
| 88 | } |
| 89 | } |
| 90 | |
| 91 | /** |
| 92 | * URLs the spec implies: one page per visible (operation, tag) pair, named by |
| 93 | * operationId — the scheme both fumadocs-openapi (groupBy: 'tag', name |
| 94 | * algorithm v2) and generate-api-index.ts encode. |
| 95 | */ |
| 96 | function expectedReferenceUrls(document: SpecDocument, baseDir: string): Set<string> { |
| 97 | const urls = new Set<string>(); |
| 98 | for (const { operation } of specOperations(document)) { |
| 99 | for (const tag of operation.tags ?? []) { |
| 100 | const tagSlug = slugifyTag(tag); |
| 101 | if (HIDDEN_API_TAGS.has(tagSlug)) continue; |
| 102 | urls.add(`/reference/${baseDir}/${tagSlug}/${operation.operationId}`); |
| 103 | } |
| 104 | } |
| 105 | return urls; |
| 106 | } |
| 107 | |
| 108 | function loadSpec(fileName: string): SpecDocument { |
| 109 | return JSON.parse(readFileSync(join(DOCS_DIR, 'public', fileName), 'utf-8')); |
| 110 | } |
| 111 | |
| 112 | /** |
| 113 | * The reference URLs production actually serves, built through the same |
| 114 | * pipeline as lib/source.ts getReferenceSource (minus the checked-in MDX |
| 115 | * collection, which bun test cannot load and which contributes no operation |
| 116 | * pages). |
| 117 | */ |
| 118 | async function generatedReferenceUrls(): Promise<Set<string>> { |
| 119 | const [latest, v3] = await Promise.all([ |
| 120 | openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }), |
| 121 | openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }), |
| 122 | ]); |
| 123 | const referenceLoader = loader({ |
| 124 | baseUrl: '/reference', |
| 125 | source: multiple({ openapi: latest, 'openapi-v3': v3 }), |
| 126 | }); |
| 127 | return new Set( |
| 128 | referenceLoader |
| 129 | .getPages() |
| 130 | .map((page) => page.url) |
| 131 | .filter((url) => !isHiddenReferenceUrl(url)), |
| 132 | ); |
| 133 | } |
| 134 | |
| 135 | const generatedUrlsPromise = generatedReferenceUrls(); |
| 136 | |
| 137 | describe('API reference route completeness', () => { |
| 138 | test('sidebar operations follow read, create, update, 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 | 'getAuthConfigs', |
| 151 | 'getAuthConfigsByNanoid', |
| 152 | 'postAuthConfigs', |
| 153 | 'patchAuthConfigsByNanoid', |
| 154 | 'patchAuthConfigsByNanoidByStatus', |
| 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']) { |
| 162 | for (const { location, operation } of specOperations(loadSpec(fileName))) { |
| 163 | const visibleTags = (operation.tags ?? []).filter( |
| 164 | (tag) => !HIDDEN_API_TAGS.has(slugifyTag(tag)), |
| 165 | ); |
| 166 | // Untagged operations fall into fumadocs' synthetic "unknown" tag, |
| 167 | // which is never declared — the page silently vanishes. |
| 168 | if ((operation.tags ?? []).length === 0) { |
| 169 | violations.push(`${fileName}: ${location} has no tags`); |
| 170 | } |
| 171 | // Without an operationId, fumadocs falls back to a path-derived file |
| 172 | // name while generate-api-index derives the href from the summary — |
| 173 | // the quick link is guaranteed to 404. |
| 174 | if (visibleTags.length > 0 && !operation.operationId) { |
| 175 | violations.push(`${fileName}: ${location} has no operationId`); |
| 176 | } |
| 177 | } |
| 178 | } |
| 179 | |
| 180 | expect(violations, violations.join('\n')).toEqual([]); |
| 181 | }); |
| 182 | |
| 183 | test('every spec operation and webhook yields exactly one generated page', async () => { |
| 184 | const expected = new Set<string>([ |
| 185 | ...expectedReferenceUrls(loadSpec('openapi.json'), 'api-reference'), |
| 186 | ...expectedReferenceUrls(loadSpec('openapi-webhooks.json'), 'api-reference'), |
| 187 | ...expectedReferenceUrls(loadSpec('openapi-v3.json'), 'v3/api-reference'), |
| 188 | ]); |
| 189 | const generated = await generatedUrlsPromise; |
| 190 | |
| 191 | const missing = [...expected].filter((url) => !generated.has(url)).sort(); |
| 192 | const extra = [...generated].filter((url) => !expected.has(url)).sort(); |
| 193 | |
| 194 | expect(expected.size).toBeGreaterThan(0); |
| 195 | expect( |
| 196 | missing, |
| 197 | `pages implied by the OpenAPI specs but not generated (silently dropped):\n${missing.join('\n')}`, |
| 198 | ).toEqual([]); |
| 199 | expect( |
| 200 | extra, |
| 201 | `generated pages not implied by the OpenAPI specs:\n${extra.join('\n')}`, |
| 202 | ).toEqual([]); |
| 203 | }); |
| 204 | |
| 205 | test('operations whose tag is undeclared are no longer dropped', async () => { |
| 206 | // The exact v10 -> v11 regression, in miniature: "Projects" is used by an |
| 207 | // operation but missing from the top-level tags array, and lib/openapi's |
| 208 | // declareOperationTags normalization is deliberately not applied. |
| 209 | // fumadocs-openapi 11.4 generates the page anyway, so this fixture now |
| 210 | // asserts the fix rather than the loss. |
| 211 | const document = { |
| 212 | openapi: '3.0.0', |
| 213 | info: { title: 'Guard fixture', version: '1' }, |
| 214 | tags: [{ name: 'Auth' }], |
| 215 | paths: { |
| 216 | '/v3.1/project/usage/summary': { |
| 217 | post: { |
| 218 | tags: ['Projects'], |
| 219 | operationId: 'postProjectUsageSummary', |
| 220 | summary: 'Usage summary', |
| 221 | responses: { '200': { description: 'ok' } }, |
| 222 | }, |
| 223 | }, |
| 224 | '/v3.1/auth/session': { |
| 225 | get: { |
| 226 | tags: ['Auth'], |
| 227 | operationId: 'getSession', |
| 228 | summary: 'Session', |
| 229 | responses: { '200': { description: 'ok' } }, |
| 230 | }, |
| 231 | }, |
| 232 | }, |
| 233 | }; |
| 234 | |
| 235 | const server = createOpenAPI({ input: { 'guard-fixture.json': document } }); |
| 236 | const source = await openapiSource(server, { groupBy: 'tag', baseDir: 'api-reference' }); |
| 237 | const generated = new Set( |
| 238 | loader({ baseUrl: '/reference', source }).getPages().map((page) => page.url), |
| 239 | ); |
| 240 | const missing = [...expectedReferenceUrls(document, 'api-reference')].filter( |
| 241 | (url) => !generated.has(url), |
| 242 | ); |
| 243 | |
| 244 | expect(generated.has('/reference/api-reference/auth/getSession')).toBe(true); |
| 245 | // Upstream fixed the silent drop, so the undeclared-tag operation now gets |
| 246 | // a page without help from declareOperationTags. That normalization is kept |
| 247 | // as a safety net for older fumadocs-openapi behaviour; if this ever fails |
| 248 | // with `missing` non-empty again, the drop has regressed upstream. The |
| 249 | // positive check guards against `missing` being vacuously empty because |
| 250 | // expectedReferenceUrls stopped yielding the projects URL. |
| 251 | expect(generated.has('/reference/api-reference/projects/postProjectUsageSummary')).toBe(true); |
| 252 | expect(missing).toEqual([]); |
| 253 | }); |
| 254 | }); |
| 255 | |
| 256 | describe('API reference quick links', () => { |
| 257 | function mdxFiles(dir: string): string[] { |
| 258 | const files: string[] = []; |
| 259 | for (const entry of readdirSync(dir, { withFileTypes: true })) { |
| 260 | const fullPath = join(dir, entry.name); |
| 261 | if (entry.isDirectory()) files.push(...mdxFiles(fullPath)); |
| 262 | else if (entry.name.endsWith('.mdx')) files.push(fullPath); |
| 263 | } |
| 264 | return files; |
| 265 | } |
| 266 | |
| 267 | /** |
| 268 | * Parses the serialized endpoints of every ApiEndpointsTable in a file. |
| 269 | * |
| 270 | * Validated through the same schema the runtime uses, not a bare |
| 271 | * JSON.parse: `mdxToCleanMarkdown` degrades a malformed payload to an empty |
| 272 | * table so one bad page cannot 500 the whole .md response, which means a |
| 273 | * structurally broken committed payload would otherwise render nothing with |
| 274 | * no failure signal anywhere. This is that signal. |
| 275 | */ |
| 276 | function parseEndpointHrefs(content: string, file: string): string[] { |
| 277 | const hrefs: string[] = []; |
| 278 | const prefix = /<ApiEndpointsTable endpoints=\{/g; |
| 279 | let match: RegExpExecArray | null; |
| 280 | while ((match = prefix.exec(content)) !== null) { |
| 281 | const start = match.index + match[0].length; |
| 282 | const end = content.indexOf('} />', start); |
| 283 | expect(end, `${file}: unterminated ApiEndpointsTable`).toBeGreaterThan(start); |
| 284 | const parsed = apiEndpointsSchema.safeParse(JSON.parse(content.slice(start, end))); |
| 285 | expect( |
| 286 | parsed.success, |
| 287 | `${file}: ApiEndpointsTable payload fails apiEndpointsSchema:\n${ |
| 288 | parsed.success ? '' : z.prettifyError(parsed.error) |
| 289 | }`, |
| 290 | ).toBe(true); |
| 291 | if (!parsed.success) continue; |
| 292 | hrefs.push(...parsed.data.map((endpoint) => endpoint.href)); |
| 293 | } |
| 294 | // A file mentioning the component but yielding no parsed table means the |
| 295 | // generator's serialization drifted from this extractor — fail loudly |
| 296 | // instead of silently checking nothing. |
| 297 | if (content.includes('<ApiEndpointsTable')) { |
| 298 | expect(hrefs.length, `${file}: found ApiEndpointsTable but extracted no hrefs`).toBeGreaterThan(0); |
| 299 | } |
| 300 | return hrefs; |
| 301 | } |
| 302 | |
| 303 | test('every ApiEndpointsTable href resolves to a generated reference page', async () => { |
| 304 | const generated = await generatedUrlsPromise; |
| 305 | const dead: string[] = []; |
| 306 | let totalHrefs = 0; |
| 307 | |
| 308 | for (const file of mdxFiles(join(DOCS_DIR, 'content/reference'))) { |
| 309 | const content = readFileSync(file, 'utf-8'); |
| 310 | for (const href of parseEndpointHrefs(content, relative(DOCS_DIR, file))) { |
| 311 | totalHrefs++; |
| 312 | if (!generated.has(href)) { |
| 313 | dead.push(`${relative(DOCS_DIR, file)}: ${href}`); |
| 314 | } |
| 315 | } |
| 316 | } |
| 317 | |
| 318 | // Sanity: the extractor must have found the generated landing pages. |
| 319 | expect(totalHrefs).toBeGreaterThan(0); |
| 320 | expect( |
| 321 | dead, |
| 322 | `quick links pointing at reference pages that are never generated (would 404):\n${dead.join('\n')}`, |
| 323 | ).toEqual([]); |
| 324 | }); |
| 325 | }); |