zudoku 0.27.0 → 0.28.0

package/src/lib/plugins/openapi/graphql/graphql.ts

@@ -31,6 +31,8 @@ export type Scalars = {
   JSON: { input: any; output: any };
   /** The `JSONObject` scalar type represents JSON objects as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf). */
   JSONObject: { input: any; output: any };
+  /** OpenAPI schema scalar type that handles circular references */
+  JSONSchema: { input: any; output: any };
 };
 
 export type EncodingItem = {
@@ -57,7 +59,7 @@ export type MediaTypeObject = {
   encoding?: Maybe<Array<EncodingItem>>;
   examples?: Maybe<Array<ExampleItem>>;
   mediaType: Scalars["String"]["output"];
-  schema?: Maybe<Scalars["JSON"]["output"]>;
+  schema?: Maybe<Scalars["JSONSchema"]["output"]>;
 };
 
 export type OperationItem = {
@@ -89,7 +91,7 @@ export type ParameterItem = {
   in: ParameterIn;
   name: Scalars["String"]["output"];
   required?: Maybe<Scalars["Boolean"]["output"]>;
-  schema?: Maybe<Scalars["JSON"]["output"]>;
+  schema?: Maybe<Scalars["JSONSchema"]["output"]>;
   style?: Maybe<Scalars["String"]["output"]>;
 };
 
@@ -132,11 +134,11 @@ export type Schema = {
   operations: Array<OperationItem>;
   paths: Array<PathItem>;
   servers: Array<Server>;
+  summary?: Maybe<Scalars["String"]["output"]>;
   tags: Array<SchemaTag>;
   title: Scalars["String"]["output"];
-  url: Scalars["String"]["output"];
+  url?: Maybe<Scalars["String"]["output"]>;
   version: Scalars["String"]["output"];
-  summary?: Maybe<Scalars["String"]["output"]>;
 };
 
 export type SchemaOperationsArgs = {
@@ -144,6 +146,7 @@ export type SchemaOperationsArgs = {
   operationId?: InputMaybe<Scalars["String"]["input"]>;
   path?: InputMaybe<Scalars["String"]["input"]>;
   tag?: InputMaybe<Scalars["String"]["input"]>;
+  untagged?: InputMaybe<Scalars["Boolean"]["input"]>;
 };
 
 export type SchemaTagsArgs = {
@@ -180,7 +183,7 @@ export type ServersQueryQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
-    url: string;
+    url?: string | null;
     servers: Array<{ __typename?: "Server"; url: string }>;
   };
 };
@@ -255,6 +258,8 @@ export type OperationsFragmentFragment = {
 export type AllOperationsQueryVariables = Exact<{
   input: Scalars["JSON"]["input"];
   type: SchemaType;
+  tag?: InputMaybe<Scalars["String"]["input"]>;
+  untagged?: InputMaybe<Scalars["Boolean"]["input"]>;
 }>;
 
 export type AllOperationsQuery = {
@@ -264,20 +269,20 @@ export type AllOperationsQuery = {
     description?: string | null;
     summary?: string | null;
     title: string;
-    url: string;
+    url?: string | null;
     version: string;
     tags: Array<{
       __typename?: "SchemaTag";
       name?: string | null;
       description?: string | null;
-      operations: Array<
-        { __typename?: "OperationItem"; slug: string } & {
-          " $fragmentRefs"?: {
-            OperationsFragmentFragment: OperationsFragmentFragment;
-          };
-        }
-      >;
     }>;
+    operations: Array<
+      { __typename?: "OperationItem"; slug: string } & {
+        " $fragmentRefs"?: {
+          OperationsFragmentFragment: OperationsFragmentFragment;
+        };
+      }
+    >;
   };
 };
 
@@ -290,7 +295,7 @@ export type GetServerQueryQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
-    url: string;
+    url?: string | null;
     servers: Array<{ __typename?: "Server"; url: string }>;
   };
 };
@@ -304,19 +309,30 @@ export type GetCategoriesQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
-    url: string;
-    tags: Array<{
-      __typename: "SchemaTag";
-      name?: string | null;
-      operations: Array<{
-        __typename: "OperationItem";
-        slug: string;
-        deprecated?: boolean | null;
-        method: string;
-        summary?: string | null;
-        operationId?: string | null;
-        path: string;
-      }>;
+    url?: string | null;
+    tags: Array<{ __typename?: "SchemaTag"; name?: string | null }>;
+  };
+};
+
+export type GetOperationsQueryVariables = Exact<{
+  input: Scalars["JSON"]["input"];
+  type: SchemaType;
+  tag?: InputMaybe<Scalars["String"]["input"]>;
+  untagged?: InputMaybe<Scalars["Boolean"]["input"]>;
+}>;
+
+export type GetOperationsQuery = {
+  __typename?: "Query";
+  schema: {
+    __typename?: "Schema";
+    operations: Array<{
+      __typename?: "OperationItem";
+      slug: string;
+      deprecated?: boolean | null;
+      method: string;
+      summary?: string | null;
+      operationId?: string | null;
+      path: string;
     }>;
   };
 };
@@ -418,20 +434,20 @@ export const ServersQueryDocument = new TypedDocumentString(`
   ServersQueryQueryVariables
 >;
 export const AllOperationsDocument = new TypedDocumentString(`
-    query AllOperations($input: JSON!, $type: SchemaType!) {
+    query AllOperations($input: JSON!, $type: SchemaType!, $tag: String, $untagged: Boolean) {
   schema(input: $input, type: $type) {
     description
     summary
     title
     url
     version
-    tags {
+    tags(name: $tag) {
       name
       description
-      operations {
-        slug
-        ...OperationsFragment
-      }
+    }
+    operations(tag: $tag, untagged: $untagged) {
+      slug
+      ...OperationsFragment
     }
   }
 }
@@ -517,17 +533,7 @@ export const GetCategoriesDocument = new TypedDocumentString(`
   schema(input: $input, type: $type) {
     url
     tags {
-      __typename
       name
-      operations {
-        __typename
-        slug
-        deprecated
-        method
-        summary
-        operationId
-        path
-      }
     }
   }
 }
@@ -535,3 +541,20 @@ export const GetCategoriesDocument = new TypedDocumentString(`
   GetCategoriesQuery,
   GetCategoriesQueryVariables
 >;
+export const GetOperationsDocument = new TypedDocumentString(`
+    query GetOperations($input: JSON!, $type: SchemaType!, $tag: String, $untagged: Boolean) {
+  schema(input: $input, type: $type) {
+    operations(tag: $tag, untagged: $untagged) {
+      slug
+      deprecated
+      method
+      summary
+      operationId
+      path
+    }
+  }
+}
+    `) as unknown as TypedDocumentString<
+  GetOperationsQuery,
+  GetOperationsQueryVariables
+>;

package/src/lib/plugins/openapi/index.tsx

@@ -1,15 +1,15 @@
-import { matchPath } from "react-router";
-import { type ZudokuPlugin } from "../../core/plugins.js";
-import { graphql } from "./graphql/index.js";
-
+import slugify from "@sindresorhus/slugify";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
+import { matchPath, redirect, RouteObject } from "react-router";
 import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
 import { useAuth } from "../../authentication/hook.js";
 import { ColorMap } from "../../components/navigation/SidebarBadge.js";
+import { type ZudokuPlugin } from "../../core/plugins.js";
 import type { SchemaImports } from "../../oas/graphql/index.js";
 import { Button } from "../../ui/Button.js";
-import { joinPath } from "../../util/joinPath.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { GraphQLClient } from "./client/GraphQLClient.js";
+import { graphql } from "./graphql/index.js";
 import { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
@@ -19,17 +19,27 @@ const GetCategoriesQuery = graphql(`
     schema(input: $input, type: $type) {
       url
       tags {
-        __typename
         name
-        operations {
-          __typename
-          slug
-          deprecated
-          method
-          summary
-          operationId
-          path
-        }
+      }
+    }
+  }
+`);
+
+const GetOperationsQuery = graphql(`
+  query GetOperations(
+    $input: JSON!
+    $type: SchemaType!
+    $tag: String
+    $untagged: Boolean
+  ) {
+    schema(input: $input, type: $type) {
+      operations(tag: $tag, untagged: $untagged) {
+        slug
+        deprecated
+        method
+        summary
+        operationId
+        path
       }
     }
   }
@@ -49,9 +59,10 @@ const MethodColorMap: Record<string, keyof typeof ColorMap> = {
 
 export type OpenApiPluginOptions = OasPluginConfig & InternalOasPluginConfig;
 
-export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
-  const basePath = joinPath(config.navigationId ?? "/reference");
+const UNTAGGED_PATH = "~endpoints";
 
+export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
+  const basePath = joinUrl(config.navigationId ?? "/reference");
   const versions = config.type === "file" ? Object.keys(config.input) : [];
 
   const client = new GraphQLClient(config);
@@ -122,41 +133,60 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
       }
 
       try {
-        const version =
-          versions.find((v) => path === joinPath(basePath, v)) ??
-          Object.keys(config.input).at(0);
+        const urlVersion = versions.find((v) =>
+          path.startsWith(joinUrl(basePath, v)),
+        );
+        const version = urlVersion ?? Object.keys(config.input).at(0);
 
         const data = await client.fetch(GetCategoriesQuery, {
           type: config.type,
           input: config.type === "file" ? config.input[version!] : config.input,
-          version,
         });
 
-        const categories = data.schema.tags
-          .filter((tag) => tag.operations.length > 0)
-          .map<SidebarItem>((tag) => ({
-            type: "category",
-            label: tag.name || "Other endpoints",
-            collapsible: true,
-            collapsed: false,
-            items: tag.operations.map((operation) => ({
-              type: "link",
-              label: operation.summary ?? operation.path,
-              href: `#${operation.slug}`,
-              badge: {
-                label: operation.method,
-                color: MethodColorMap[operation.method.toLowerCase()]!,
-                invert: true,
-              },
-            })),
-          }));
+        const tag = config.tagPages?.find(
+          (tag) => path.split("/").at(-1) === slugify(tag),
+        );
 
-        categories.unshift({
-          type: "link",
-          label: "Overview",
-          href: "#description",
+        const operationsData = await client.fetch(GetOperationsQuery, {
+          type: config.type,
+          input: config.type === "file" ? config.input[version!] : config.input,
+          tag,
+          untagged: tag === undefined,
         });
 
+        const items = operationsData.schema.operations.map((operation) => ({
+          type: "link" as const,
+          label: operation.summary ?? operation.path,
+          href: `#${operation.slug}`,
+          badge: {
+            label: operation.method,
+            color: MethodColorMap[operation.method.toLowerCase()]!,
+            invert: true,
+          } as const,
+        }));
+
+        const categories = data.schema.tags
+          // .filter((tag) => tag.operations.length > 0)
+          .map<SidebarItem>((tag) => {
+            const categoryLink = joinUrl(
+              basePath,
+              urlVersion,
+              tag.name ? slugify(tag.name) : UNTAGGED_PATH,
+            );
+            return {
+              type: "category",
+              label: tag.name || "Other endpoints",
+              link: {
+                type: "doc" as const,
+                id: categoryLink,
+                label: tag.name!,
+              },
+              collapsible: false,
+              collapsed: true,
+              items: path === categoryLink ? items : [],
+            };
+          });
+
         return categories;
       } catch {
         return [];
@@ -165,31 +195,59 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
     getRoutes: () => {
       const versionsInPath = [null, ...versions];
 
-      return versionsInPath.map((version) => ({
-        path: basePath + (version ? `/${version}` : ""),
-        async lazy() {
-          const { OpenApiRoute } = await import("./Route.js");
-          return {
-            element: (
-              <OpenApiRoute
-                basePath={basePath}
-                versions={versions}
-                client={client}
-                config={config}
-              />
-            ),
-          };
-        },
-        children: [
-          {
-            index: true,
-            async lazy() {
-              const { OperationList } = await import("./OperationList.js");
-              return { element: <OperationList /> };
-            },
-          },
-        ],
+      const tagPages = (config.tagPages ?? []).map((tag) => ({
+        tag,
+        path: slugify(tag),
       }));
+
+      return versionsInPath.map((version) => {
+        const versionPath = joinUrl(basePath, version ? `/${version}` : "");
+
+        return {
+          path: versionPath,
+          async lazy() {
+            const { OpenApiRoute } = await import("./OpenApiRoute.js");
+            return {
+              element: (
+                <OpenApiRoute
+                  version={version ?? undefined}
+                  basePath={basePath}
+                  versions={versions}
+                  client={client}
+                  config={config}
+                />
+              ),
+            };
+          },
+          children: [
+            {
+              index: true,
+              loader: () =>
+                redirect(
+                  joinUrl(versionPath, tagPages.at(0)?.path ?? UNTAGGED_PATH),
+                ),
+            },
+            {
+              path: joinUrl(versionPath, UNTAGGED_PATH),
+              async lazy() {
+                const { OperationList } = await import("./OperationList.js");
+                return { element: <OperationList untagged={true} /> };
+              },
+            },
+            ...tagPages.map<RouteObject>((tag) => {
+              return {
+                path: joinUrl(versionPath, tag.path),
+                async lazy() {
+                  const { OperationList } = await import("./OperationList.js");
+                  return {
+                    element: <OperationList tag={tag.tag} />,
+                  };
+                },
+              };
+            }),
+          ],
+        };
+      });
     },
   };
 };

package/src/lib/plugins/openapi/interfaces.ts

@@ -20,6 +20,7 @@ export type OasPluginConfig = {
   server?: string;
   navigationId?: string;
   skipPreload?: boolean;
+  tagPages?: Array<string>;
 } & OasPluginConfigOptions &
   OasSource;
 

package/src/lib/util/joinUrl.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { joinUrl } from "./joinUrl.js";
+
+describe("joinUrl", () => {
+  test("handles basic URL joining", () => {
+    expect(joinUrl("https://example.com", "path")).toBe(
+      "https://example.com/path",
+    );
+    expect(joinUrl("https://example.com/", "path")).toBe(
+      "https://example.com/path",
+    );
+    expect(joinUrl("https://example.com/", "/path")).toBe(
+      "https://example.com/path",
+    );
+  });
+
+  test("handles multiple path segments", () => {
+    expect(joinUrl("https://example.com", "api", "v1", "users")).toBe(
+      "https://example.com/api/v1/users",
+    );
+  });
+
+  // test("handles query parameters", () => {
+  //   expect(joinUrl("https://example.com", "path?query=1")).toBe(
+  //     "https://example.com/path?query=1",
+  //   );
+  //   expect(joinUrl("https://example.com?base=1", "path?query=1")).toBe(
+  //     "https://example.com/path?query=1",
+  //   );
+  // });
+
+  // test("handles repeated dots and question marks", () => {
+  //   expect(joinUrl("https://example.com", "path/../../../test")).toBe(
+  //     "https://example.com/path/../../../test",
+  //   );
+  //   expect(joinUrl("https://example.com", "test????a=1")).toBe(
+  //     "https://example.com/test????a=1",
+  //   );
+  // });
+
+  test("handles falsy values", () => {
+    expect(joinUrl("https://example.com", null, undefined, false, "path")).toBe(
+      "https://example.com/path",
+    );
+  });
+
+  test("handles numeric values", () => {
+    expect(joinUrl("https://example.com", "api", 123, "test")).toBe(
+      "https://example.com/api/123/test",
+    );
+  });
+
+  test("handles relative paths", () => {
+    expect(joinUrl("/api", "v1", "users")).toBe("/api/v1/users");
+    expect(joinUrl("api", "v1", "users")).toBe("/api/v1/users");
+  });
+
+  test("handles empty input", () => {
+    expect(joinUrl()).toBe("/");
+    expect(joinUrl("")).toBe("/");
+  });
+});

package/src/lib/util/joinUrl.ts

@@ -1,5 +1,5 @@
 // Mostly adapted from https://github.com/moxystudio/js-proper-url-join
-const defaultUrlRegExp = /^(\w+:\/\/[^/?]+)?(.*?)(\?.+)?$/;
+const defaultUrlRegExp = /^(\w+:\/\/[^/?]+)?([^?]*)(\?.*)?$/;
 
 const normalizeParts = (
   parts: (string | number | null | undefined | false)[],

package/dist/lib/plugins/openapi/Route.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Route.js","sourceRoot":"","sources":["../../../../src/lib/plugins/openapi/Route.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAC3B,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,MAAM,GAMP,EAAE,EAAE;IACH,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,EAAa,CAAC;IAE3C,MAAM,KAAK,GACT,MAAM,CAAC,IAAI,KAAK,MAAM;QACpB,CAAC,CAAC;YACE,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,OAAO;gBACZ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAE;gBACxB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAE;SACvC;QACH,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;IAEjD,MAAM,cAAc,GAAG,OAAO,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEjD,OAAO,CACL,KAAC,iBAAiB,IAChB,KAAK,EAAE;YACL,MAAM,EAAE;gBACN,GAAG,MAAM;gBACT,OAAO,EAAE,cAAc;gBACvB,QAAQ,EAAE,MAAM,CAAC,WAAW,CAC1B,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAClE;gBACD,GAAG,KAAK;aACT;SACF,YAED,KAAC,eAAe,IAAC,MAAM,EAAE,MAAM,YAC7B,KAAC,MAAM,KAAG,GACM,GACA,CACrB,CAAC;AACJ,CAAC,CAAC"}