Derive unique version paths and labels from query params for schema inputs

Author: dan-lee

docs/pages/docs/guides/processors.mdx

@@ -170,11 +170,28 @@ argument, allowing you to filter or transform the schema differently for each va
 This is useful when you have a single schema containing multiple API versions or groups that you
 want to split into separate pages.
 
+Plain strings work out of the box. Version paths and dropdown labels are auto-generated from the
+query parameter values. For more control, use the object form with explicit `path` and `label`.
+
 ```ts title=zudoku.config.ts
 const config = {
   apis: {
     type: "file",
-    input: ["openapi.json?prefix=/v2", "openapi.json?prefix=/v1"],
+    input: [
+      // Object form: explicit path and label
+      {
+        input: "openapi.json?prefix=/v2",
+        path: "latest",
+        label: "Latest (v2)",
+      },
+      // Object form: explicit path, label auto-generated from params
+      {
+        input: "openapi.json?prefix=/v1.1",
+        path: "v1.1",
+      },
+      // Plain string: both path and label auto-generated from params
+      "openapi.json?prefix=/v1",
+    ],
     path: "/api",
   },
 };

packages/zudoku/src/lib/plugins/openapi/ApiHeader.tsx

@@ -60,7 +60,7 @@ export const ApiHeader = ({
             {showVersions && (
               <span className="text-xl text-muted-foreground ms-1.5">
                 {" "}
-                ({version})
+                ({currentVersion?.label ?? version})
               </span>
             )}
           </Heading>

packages/zudoku/src/vite/api/SchemaManager.test.ts

@@ -274,6 +274,12 @@ describe("SchemaManager", () => {
 
     expect(schemas?.[0]?.importKey).not.toBe(schemas?.[1]?.importKey);
 
+    // Auto-generated version paths are unique when using query params
+    expect(schemas?.[0]?.path).not.toBe(schemas?.[1]?.path);
+    // Auto-generated labels from param values
+    expect(schemas?.[0]?.label).toBe("/v1");
+    expect(schemas?.[1]?.label).toBe("/v2");
+
     const v1Paths = Object.keys(schemas?.[0]?.schema.paths ?? {});
     const v2Paths = Object.keys(schemas?.[1]?.schema.paths ?? {});
     expect(v1Paths).toEqual(["/v1/users", "/v1/posts"]);

packages/zudoku/src/vite/api/SchemaManager.ts

@@ -50,6 +50,13 @@ const paramsSuffix = (params: Record<string, string>) =>
     ? `-${slugify(new URLSearchParams(params).toString(), { separator: "_" })}`
     : "";
 
+const paramsPath = (params: Record<string, string>) =>
+  Object.keys(params).length > 0
+    ? Object.values(params)
+        .map((v) => slugify(v))
+        .join("-")
+    : "";
+
 const normalizeInputs = (
   inputs:
     | string
@@ -188,13 +195,17 @@ export class SchemaManager {
     const versionPath =
       existingSchema?.path && existingSchema.path.length > 0
         ? existingSchema.path
-        : schemaVersion;
+        : paramsPath(params) || schemaVersion;
 
     const processed = {
       schema: processedSchema,
       version: schemaVersion,
       path: versionPath,
-      label: existingSchema?.label,
+      label:
+        existingSchema?.label ??
+        (Object.keys(params).length > 0
+          ? Object.values(params).join(", ")
+          : undefined),
       inputPath: filePath,
       params,
       importKey,