fix(docs): validate generated API navigation (#7099)

apps/docs/lib/openapi-source.test.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { loader, multiple } from 'fumadocs-core/source'
+import { describe, expect, it } from 'vitest'
+import { i18n } from '@/lib/i18n'
+import { createApiReferenceSource } from '@/lib/openapi-source'
+
+interface ApiReferenceMeta {
+  pages: string[]
+}
+
+describe('OpenAPI source', () => {
+  it('resolves every generated navigation group for every locale', async () => {
+    const source = loader(multiple({ openapi: await createApiReferenceSource() }), {
+      baseUrl: '/',
+      i18n,
+    })
+
+    for (const locale of i18n.languages) {
+      const metaPath = path.resolve(
+        import.meta.dirname,
+        `../content/docs/${locale}/api-reference/meta.json`
+      )
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as ApiReferenceMeta
+      const generatedGroups = meta.pages.filter((page) => page.startsWith('(generated)/'))
+
+      expect(generatedGroups).toContain('(generated)/catalog')
+      expect(generatedGroups).toContain('(generated)/meta')
+
+      const pages = source.getPages(locale)
+      for (const group of generatedGroups) {
+        const groupSlug = group.replace('(generated)/', '')
+        const localePrefix = locale === i18n.defaultLanguage ? '' : `/${locale}`
+        const groupUrlPrefix = `${localePrefix}/api-reference/${groupSlug}/`
+        expect(pages.some((page) => page.url.startsWith(groupUrlPrefix))).toBe(true)
+      }
+    }
+  })
+})

apps/docs/lib/openapi-source.ts

@@ -0,0 +1,10 @@
+import { openapiSource } from 'fumadocs-openapi/server'
+import { openapi } from '@/lib/openapi'
+
+/** Generates the virtual API-reference pages consumed by the docs source loader. */
+export function createApiReferenceSource() {
+  return openapiSource(openapi, {
+    baseDir: 'en/api-reference/(generated)',
+    groupBy: 'tag',
+  })
+}

apps/docs/lib/source.ts

@@ -1,10 +1,9 @@
 import { createElement, Fragment } from 'react'
 import { loader, multiple } from 'fumadocs-core/source'
 import type { DocData, DocMethods } from 'fumadocs-mdx/runtime/types'
-import { openapiSource } from 'fumadocs-openapi/server'
 import { docs } from '@/.source/server'
 import { i18n } from './i18n'
-import { openapi } from './openapi'
+import { createApiReferenceSource } from './openapi-source'
 
 const METHOD_COLORS: Record<string, string> = {
   GET: 'text-green-600 dark:text-green-400',
@@ -80,10 +79,7 @@ function openapiPluginBadgeLeft() {
 export const source = loader(
   multiple({
     docs: docs.toFumadocsSource(),
-    openapi: await openapiSource(openapi, {
-      baseDir: 'en/api-reference/(generated)',
-      groupBy: 'tag',
-    }),
+    openapi: await createApiReferenceSource(),
   }),
   {
     baseUrl: '/',

apps/docs/vitest.config.ts

@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('.', import.meta.url)),
+    },
+  },
+})

scripts/check-openapi-specs.ts

@@ -109,6 +109,8 @@ const REQUIRED_API_REFERENCE_GROUPS = [
   '(generated)/custom-tools',
   '(generated)/credentials',
   '(generated)/secrets',
+  '(generated)/catalog',
+  '(generated)/meta',
 ] as const
 const REMOVED_API_REFERENCE_GROUPS = [
   '(generated)/execution',