OpenAPI: Improve generateFiles warnings

.changeset/dull-maps-heal.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-openapi': patch
+---
+
+Improve `generateFiles` warnings

apps/docs/content/docs/ui/(integrations)/openapi/index.mdx

@@ -5,42 +5,6 @@ description: Generating docs for OpenAPI schema
 
 You can setup Fumadocs OpenAPI manually, or use Fumadocs CLI.
 
-## Auto Setup
-
-Using Fumadocs CLI.
-
-<Tabs groupId='package-manager' persist items={['npm', 'pnpm', 'yarn', 'bun']}>
-
-```bash tab="npm"
-# install the CLI package, if you haven't installed it yet
-npm install @fumadocs/cli --save-dev
-
-npx fumadocs init openapi
-```
-
-```bash tab="pnpm"
-# install the CLI package, if you haven't installed it yet
-pnpm add @fumadocs/cli --save-dev
-
-pnpm fumadocs init openapi
-```
-
-```bash tab="yarn"
-# install the CLI package, if you haven't installed it yet
-yarn add @fumadocs/cli ---dev
-
-yarn fumadocs init openapi
-```
-
-```bash tab="bun"
-# install the CLI package, if you haven't installed it yet
-bun add @fumadocs/cli ---dev
-
-bun fumadocs init openapi
-```
-
-</Tabs>
-
 ## Manual Setup
 
 Install the required packages.
@@ -71,7 +35,16 @@ Add the package to `@source` in your Tailwind CSS configuration.
 Create an OpenAPI instance on the server. Fumadocs OpenAPI renders the pages on server-side.
 
 ```ts title="lib/source.ts"
-import { createOpenAPI } from 'fumadocs-openapi/server';
+import { createOpenAPI, attachFile } from 'fumadocs-openapi/server';
+import { loader } from 'fumadocs-core/source';
+
+export const source = loader({
+  pageTree: {
+    // adds a badge to each page item in page tree
+    attachFile,
+  },
+  // other props
+});
 
 export const openapi = createOpenAPI({
   // options
@@ -117,24 +90,6 @@ Generate docs with the script:
 node ./scripts/generate-docs.mjs
 ```
 
-### Generate Page Tree
-
-You can add the `attachFile` to decorate the page tree with Source API.
-
-It adds a badge to each page item.
-
-```ts title="lib/source.ts"
-import { loader } from 'fumadocs-core/source';
-import { attachFile } from 'fumadocs-openapi/server';
-
-export const utils = loader({
-  pageTree: {
-    attachFile,
-  },
-  // other props
-});
-```
-
 ## Features
 
 The official OpenAPI integration supports:

package.json

@@ -19,7 +19,6 @@
   "devDependencies": {
     "@changesets/cli": "^2.28.1",
     "@eslint/js": "^9.24.0",
-    "@types/eslint__js": "^9.14.0",
     "concurrently": "^9.1.2",
     "eslint": "^9.24.0",
     "eslint-plugin-react": "^7.37.5",

packages/openapi/src/generate-file.ts

@@ -102,18 +102,17 @@ export async function generateFiles(options: Config): Promise<void> {
     const outPaths: string[] = [];
 
     if (groupBy === 'tag') {
-      const tags = result.operation.tags;
-
-      if (tags && tags.length > 0) {
-        for (const tag of tags) {
-          outPaths.push(join(outputDir, getFilename(tag), `${file}.mdx`));
-        }
-      } else {
-        outPaths.push(
-          result.type === 'operation'
-            ? join(outputDir, `${file}.mdx`)
-            : join(outputDir, 'webhooks', `${file}.mdx`),
+      let tags = result.operation.tags;
+      if (!tags || tags.length === 0) {
+        console.warn(
+          'When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.',
         );
+
+        tags = ['unknown'];
+      }
+
+      for (const tag of tags) {
+        outPaths.push(join(outputDir, getFilename(tag), `${file}.mdx`));
       }
     } else {
       outPaths.push(join(outputDir, `${file}.mdx`));
@@ -147,16 +146,20 @@ export async function generateFiles(options: Config): Promise<void> {
       const results = await generatePages(pathOrUrl, options);
 
       for (const result of results) {
-        for (const outPath of getOutputPaths(result)) {
-          await write(outPath, result.content);
-          console.log(`Generated: ${outPath}`);
+        const outputPaths = getOutputPaths(result);
+        await Promise.all(
+          outputPaths.map(async (outPath) => {
+            await write(outPath, result.content);
 
-          if (groupBy === 'route' && result.pathItem.summary) {
-            await writeMetafile(join(dirname(outPath), 'meta.json'), {
-              title: result.pathItem.summary,
-            });
-          }
-        }
+            if (groupBy === 'route' && result.pathItem.summary) {
+              await writeMetafile(join(dirname(outPath), 'meta.json'), {
+                title: result.pathItem.summary,
+              });
+            }
+          }),
+        );
+
+        console.log(`Generated: ${outputPaths.join(', ')}`);
       }
     }
 

pnpm-lock.yaml

@@ -14,9 +14,6 @@ importers:
       '@eslint/js':
         specifier: ^9.24.0
         version: 9.24.0
-      '@types/eslint__js':
-        specifier: ^9.14.0
-        version: 9.14.0
       concurrently:
         specifier: ^9.1.2
         version: 9.1.2
@@ -4205,10 +4202,6 @@ packages:
   '@types/[email protected]':
     resolution: {integrity: sha512-FXx2pKgId/WyYo2jXw63kk7/+TY7u7AziEJxJAnSFzHlqTAS3Ync6SvgYAN/k4/PQpnnVuzoMuVnByKK2qp0ag==}
 
-  '@types/[email protected]':
-    resolution: {integrity: sha512-s0jepCjOJWB/GKcuba4jISaVpBudw3ClXJ3fUK4tugChUMQsp6kSwuA8Dcx6wFd/JsJqcY8n4rEpa5RTHs5ypA==}
-    deprecated: This is a stub types definition. @eslint/js provides its own type definitions, so you do not need this installed.
-
   '@types/[email protected]':
     resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
 
@@ -12824,10 +12817,6 @@ snapshots:
       '@types/estree': 1.0.7
       '@types/json-schema': 7.0.15
 
-  '@types/[email protected]':
-    dependencies:
-      '@eslint/js': 9.24.0
-
   '@types/[email protected]':
     dependencies:
       '@types/estree': 1.0.7