zudoku 0.0.0-f01b653 → 0.0.0-f06d326

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

@@ -31,6 +31,13 @@ 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 Components = {
+  __typename?: "Components";
+  schemas?: Maybe<Array<SchemaItem>>;
 };
 
 export type EncodingItem = {
@@ -57,7 +64,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 = {
@@ -65,6 +72,7 @@ export type OperationItem = {
   contentTypes: Array<Scalars["String"]["output"]>;
   deprecated?: Maybe<Scalars["Boolean"]["output"]>;
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   method: Scalars["String"]["output"];
   operationId?: Maybe<Scalars["String"]["output"]>;
   parameters?: Maybe<Array<ParameterItem>>;
@@ -86,10 +94,11 @@ export type ParameterItem = {
   description?: Maybe<Scalars["String"]["output"]>;
   examples?: Maybe<Array<ExampleItem>>;
   explode?: Maybe<Scalars["Boolean"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   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"]>;
 };
 
@@ -120,6 +129,7 @@ export type ResponseItem = {
   __typename?: "ResponseItem";
   content?: Maybe<Array<MediaTypeObject>>;
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   headers?: Maybe<Scalars["JSON"]["output"]>;
   links?: Maybe<Scalars["JSON"]["output"]>;
   statusCode: Scalars["String"]["output"];
@@ -127,16 +137,19 @@ export type ResponseItem = {
 
 export type Schema = {
   __typename?: "Schema";
+  components?: Maybe<Components>;
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   openapi: Scalars["String"]["output"];
   operations: Array<OperationItem>;
   paths: Array<PathItem>;
   servers: Array<Server>;
+  summary?: Maybe<Scalars["String"]["output"]>;
+  tag?: Maybe<SchemaTag>;
   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,17 +157,32 @@ 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 = {
+export type SchemaTagArgs = {
   name?: InputMaybe<Scalars["String"]["input"]>;
+  slug?: InputMaybe<Scalars["String"]["input"]>;
+  untagged?: InputMaybe<Scalars["Boolean"]["input"]>;
+};
+
+export type SchemaItem = {
+  __typename?: "SchemaItem";
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
+  name: Scalars["String"]["output"];
+  schema: Scalars["JSONSchema"]["output"];
 };
 
 export type SchemaTag = {
   __typename?: "SchemaTag";
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
+  isUntagged: Scalars["Boolean"]["output"];
   name?: Maybe<Scalars["String"]["output"]>;
+  next?: Maybe<SchemaTag>;
   operations: Array<OperationItem>;
+  prev?: Maybe<SchemaTag>;
+  slug?: Maybe<Scalars["String"]["output"]>;
 };
 
 export type SchemaType = "file" | "raw" | "url";
@@ -168,6 +196,7 @@ export type Server = {
 export type TagItem = {
   __typename?: "TagItem";
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   name: Scalars["String"]["output"];
 };
 
@@ -180,7 +209,7 @@ export type ServersQueryQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
-    url: string;
+    url?: string | null;
     servers: Array<{ __typename?: "Server"; url: string }>;
   };
 };
@@ -194,6 +223,8 @@ export type OperationsFragmentFragment = {
   operationId?: string | null;
   contentTypes: Array<string>;
   path: string;
+  deprecated?: boolean | null;
+  extensions?: any | null;
   parameters?: Array<{
     __typename?: "ParameterItem";
     name: string;
@@ -202,6 +233,7 @@ export type OperationsFragmentFragment = {
     required?: boolean | null;
     schema?: any | null;
     style?: string | null;
+    explode?: boolean | null;
     examples?: Array<{
       __typename?: "ExampleItem";
       name: string;
@@ -252,21 +284,34 @@ export type OperationsFragmentFragment = {
   }>;
 } & { " $fragmentName"?: "OperationsFragmentFragment" };
 
-export type AllOperationsQueryVariables = Exact<{
+export type SchemaWarmupQueryVariables = Exact<{
+  input: Scalars["JSON"]["input"];
+  type: SchemaType;
+}>;
+
+export type SchemaWarmupQuery = {
+  __typename?: "Query";
+  schema: { __typename?: "Schema"; openapi: string };
+};
+
+export type OperationsForTagQueryVariables = Exact<{
   input: Scalars["JSON"]["input"];
   type: SchemaType;
+  tag?: InputMaybe<Scalars["String"]["input"]>;
+  untagged?: InputMaybe<Scalars["Boolean"]["input"]>;
 }>;
 
-export type AllOperationsQuery = {
+export type OperationsForTagQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
     description?: string | null;
     summary?: string | null;
     title: string;
-    url: string;
+    url?: string | null;
     version: string;
-    tags: Array<{
+    servers: Array<{ __typename?: "Server"; url: string }>;
+    tag?: {
       __typename?: "SchemaTag";
       name?: string | null;
       description?: string | null;
@@ -277,7 +322,41 @@ export type AllOperationsQuery = {
           };
         }
       >;
-    }>;
+      next?: {
+        __typename?: "SchemaTag";
+        name?: string | null;
+        slug?: string | null;
+      } | null;
+      prev?: {
+        __typename?: "SchemaTag";
+        name?: string | null;
+        slug?: string | null;
+      } | null;
+    } | null;
+  };
+};
+
+export type GetSchemasQueryVariables = Exact<{
+  input: Scalars["JSON"]["input"];
+  type: SchemaType;
+}>;
+
+export type GetSchemasQuery = {
+  __typename?: "Query";
+  schema: {
+    __typename?: "Schema";
+    title: string;
+    description?: string | null;
+    summary?: string | null;
+    components?: {
+      __typename?: "Components";
+      schemas?: Array<{
+        __typename?: "SchemaItem";
+        name: string;
+        schema: any;
+        extensions?: any | null;
+      }> | null;
+    } | null;
   };
 };
 
@@ -290,34 +369,38 @@ export type GetServerQueryQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
-    url: string;
+    url?: string | null;
     servers: Array<{ __typename?: "Server"; url: string }>;
   };
 };
 
-export type GetCategoriesQueryVariables = Exact<{
+export type GetSidebarOperationsQueryVariables = Exact<{
   input: Scalars["JSON"]["input"];
   type: SchemaType;
 }>;
 
-export type GetCategoriesQuery = {
+export type GetSidebarOperationsQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
-    url: string;
     tags: Array<{
-      __typename: "SchemaTag";
+      __typename?: "SchemaTag";
+      slug?: string | null;
       name?: string | null;
+      extensions?: any | null;
       operations: Array<{
-        __typename: "OperationItem";
+        __typename?: "OperationItem";
+        summary?: string | null;
         slug: string;
-        deprecated?: boolean | null;
         method: string;
-        summary?: string | null;
         operationId?: string | null;
         path: string;
       }>;
     }>;
+    components?: {
+      __typename?: "Components";
+      schemas?: Array<{ __typename: "SchemaItem" }> | null;
+    } | null;
   };
 };
 
@@ -326,12 +409,13 @@ export class TypedDocumentString<TResult, TVariables>
   implements DocumentTypeDecoration<TResult, TVariables>
 {
   __apiType?: DocumentTypeDecoration<TResult, TVariables>["__apiType"];
+  private value: string;
+  public __meta__?: Record<string, any> | undefined;
 
-  constructor(
-    private value: string,
-    public __meta__?: Record<string, any> | undefined,
-  ) {
+  constructor(value: string, __meta__?: Record<string, any> | undefined) {
     super(value);
+    this.value = value;
+    this.__meta__ = __meta__;
   }
 
   toString(): string & DocumentTypeDecoration<TResult, TVariables> {
@@ -348,6 +432,8 @@ export const OperationsFragmentFragmentDoc = new TypedDocumentString(
   operationId
   contentTypes
   path
+  deprecated
+  extensions
   parameters {
     name
     in
@@ -355,6 +441,7 @@ export const OperationsFragmentFragmentDoc = new TypedDocumentString(
     required
     schema
     style
+    explode
     examples {
       name
       description
@@ -417,21 +504,42 @@ export const ServersQueryDocument = new TypedDocumentString(`
   ServersQueryQuery,
   ServersQueryQueryVariables
 >;
-export const AllOperationsDocument = new TypedDocumentString(`
-    query AllOperations($input: JSON!, $type: SchemaType!) {
+export const SchemaWarmupDocument = new TypedDocumentString(`
+    query SchemaWarmup($input: JSON!, $type: SchemaType!) {
   schema(input: $input, type: $type) {
+    openapi
+  }
+}
+    `) as unknown as TypedDocumentString<
+  SchemaWarmupQuery,
+  SchemaWarmupQueryVariables
+>;
+export const OperationsForTagDocument = new TypedDocumentString(`
+    query OperationsForTag($input: JSON!, $type: SchemaType!, $tag: String, $untagged: Boolean) {
+  schema(input: $input, type: $type) {
+    servers {
+      url
+    }
     description
     summary
     title
     url
     version
-    tags {
+    tag(slug: $tag, untagged: $untagged) {
       name
       description
       operations {
         slug
         ...OperationsFragment
       }
+      next {
+        name
+        slug
+      }
+      prev {
+        name
+        slug
+      }
     }
   }
 }
@@ -443,6 +551,8 @@ export const AllOperationsDocument = new TypedDocumentString(`
   operationId
   contentTypes
   path
+  deprecated
+  extensions
   parameters {
     name
     in
@@ -450,6 +560,7 @@ export const AllOperationsDocument = new TypedDocumentString(`
     required
     schema
     style
+    explode
     examples {
       name
       description
@@ -496,8 +607,27 @@ export const AllOperationsDocument = new TypedDocumentString(`
     }
   }
 }`) as unknown as TypedDocumentString<
-  AllOperationsQuery,
-  AllOperationsQueryVariables
+  OperationsForTagQuery,
+  OperationsForTagQueryVariables
+>;
+export const GetSchemasDocument = new TypedDocumentString(`
+    query GetSchemas($input: JSON!, $type: SchemaType!) {
+  schema(input: $input, type: $type) {
+    title
+    description
+    summary
+    components {
+      schemas {
+        name
+        schema
+        extensions
+      }
+    }
+  }
+}
+    `) as unknown as TypedDocumentString<
+  GetSchemasQuery,
+  GetSchemasQueryVariables
 >;
 export const GetServerQueryDocument = new TypedDocumentString(`
     query getServerQuery($input: JSON!, $type: SchemaType!) {
@@ -512,26 +642,29 @@ export const GetServerQueryDocument = new TypedDocumentString(`
   GetServerQueryQuery,
   GetServerQueryQueryVariables
 >;
-export const GetCategoriesDocument = new TypedDocumentString(`
-    query GetCategories($input: JSON!, $type: SchemaType!) {
+export const GetSidebarOperationsDocument = new TypedDocumentString(`
+    query GetSidebarOperations($input: JSON!, $type: SchemaType!) {
   schema(input: $input, type: $type) {
-    url
     tags {
-      __typename
+      slug
       name
+      extensions
       operations {
-        __typename
+        summary
         slug
-        deprecated
         method
-        summary
         operationId
         path
       }
     }
+    components {
+      schemas {
+        __typename
+      }
+    }
   }
 }
     `) as unknown as TypedDocumentString<
-  GetCategoriesQuery,
-  GetCategoriesQueryVariables
+  GetSidebarOperationsQuery,
+  GetSidebarOperationsQueryVariables
 >;

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

@@ -1,57 +1,52 @@
-import { matchPath, type RouteObject } from "react-router";
-import { type ZudokuPlugin } from "../../core/plugins.js";
-import { graphql } from "./graphql/index.js";
-
-import { useQuery } from "@tanstack/react-query";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
+import { type ReactNode } from "react";
+import { matchPath } from "react-router";
 import { useAuth } from "../../authentication/hook.js";
-import { ColorMap } from "../../components/navigation/SidebarBadge.js";
+import { type ZudokuPlugin } from "../../core/plugins.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 { OasPluginConfig } from "./interfaces.js";
+import type { GetSidebarOperationsQuery } from "./graphql/graphql.js";
+import { graphql } from "./graphql/index.js";
+import { type OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
+import { createSidebarCategory } from "./util/createSidebarCategory.js";
+import { getRoutes, getVersions } from "./util/getRoutes.js";
 
-const GetCategoriesQuery = graphql(`
-  query GetCategories($input: JSON!, $type: SchemaType!) {
+const GetSidebarOperationsQuery = graphql(`
+  query GetSidebarOperations($input: JSON!, $type: SchemaType!) {
     schema(input: $input, type: $type) {
-      url
       tags {
-        __typename
+        slug
         name
+        extensions
         operations {
-          __typename
+          summary
           slug
-          deprecated
           method
-          summary
           operationId
           path
         }
       }
+      components {
+        schemas {
+          __typename
+        }
+      }
     }
   }
 `);
 
-type InternalOasPluginConfig = { inMemory?: boolean };
-
-const MethodColorMap: Record<string, keyof typeof ColorMap> = {
-  get: "green",
-  post: "blue",
-  put: "yellow",
-  delete: "red",
-  patch: "purple",
-  options: "gray",
-  head: "gray",
-};
+export type OperationResult =
+  GetSidebarOperationsQuery["schema"]["tags"][number]["operations"][number];
 
-export type OpenApiPluginOptions = OasPluginConfig & InternalOasPluginConfig;
+export type OpenApiPluginOptions = OasPluginConfig;
 
-export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
-  const basePath = joinPath(config.navigationId ?? "/reference");
+export const UNTAGGED_PATH = "~endpoints";
 
+export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
+  const basePath = joinUrl(config.navigationId ?? "/reference");
   const client = new GraphQLClient(config);
 
   return {
@@ -77,19 +72,19 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
         server,
         method,
         url,
+        children,
         ...props
-      }: Partial<PlaygroundContentProps> & { requireAuth: boolean }) => {
+      }: Partial<PlaygroundContentProps> & { children: ReactNode } & Pick<
+          PlaygroundContentProps,
+          "server"
+        > & {
+          requireAuth: boolean;
+        }) => {
         const auth = useAuth();
-        // We don't have the GraphQL context here
-        const serverQuery = useQuery({
-          queryFn: () =>
-            client.fetch(GetCategoriesQuery, {
-              type: config.type,
-              input: config.input,
-            }),
-          enabled: !server,
-          queryKey: ["playground-server"],
-        });
+
+        if (!server) {
+          throw new Error("Server is required");
+        }
 
         if (requireAuth && !auth.isAuthenticated) {
           return (
@@ -107,84 +102,90 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
           <PlaygroundDialog
             url={url ?? "/"}
             method={method ?? "get"}
-            server={
-              server ?? serverQuery.data?.schema.url ?? "https://example.com"
-            }
+            server={server}
             {...props}
           >
             <Button className="gap-2 items-center" variant="outline">
-              Open in Playground <CirclePlayIcon size={16} />
+              {children ?? (
+                <>
+                  Open in Playground <CirclePlayIcon size={16} />
+                </>
+              )}
             </Button>
           </PlaygroundDialog>
         );
       },
     }),
-    getSidebar: async (path: string) => {
+    getSidebar: async (path, context) => {
       if (!matchPath({ path: basePath, end: false }, path)) {
         return [];
       }
 
+      const match = matchPath(
+        { path: `${basePath}/:version?/:tag`, end: true },
+        path,
+      );
+
       try {
-        const data = await client.fetch(GetCategoriesQuery, {
-          type: config.type,
-          input: config.input,
+        const versionParam = match?.params.version;
+        const version = versionParam ?? getVersions(config).at(0);
+        const { type } = config;
+        const input = type === "file" ? config.input[version!] : config.input;
+
+        const data = await context.queryClient.ensureQueryData({
+          queryKey: ["sidebar-operations-query", input],
+          queryFn: () =>
+            client.fetch(GetSidebarOperationsQuery, { type, input }),
         });
 
-        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()]!,
-              },
-            })),
-          }));
-
-        categories.unshift({
-          type: "link",
-          label: "Overview",
-          href: "#description",
+        const categories = data.schema.tags.flatMap((tag) => {
+          if (!tag.name || tag.operations.length === 0) return [];
+
+          const categoryPath = joinUrl(basePath, versionParam, tag.slug);
+
+          const isCollapsed =
+            tag.extensions?.["x-zudoku-collapsed"] ??
+            !config.options?.expandAllTags;
+          const isCollapsible =
+            tag.extensions?.["x-zudoku-collapsible"] ?? true;
+
+          return createSidebarCategory({
+            label: tag.name,
+            path: categoryPath,
+            operations: tag.operations,
+            collapsed: isCollapsed,
+            collapsible: isCollapsible,
+          });
         });
 
+        const untaggedOperations = data.schema.tags.find(
+          (tag) => !tag.name,
+        )?.operations;
+
+        if (untaggedOperations) {
+          categories.push(
+            createSidebarCategory({
+              label: "Other endpoints",
+              path: joinUrl(basePath, versionParam, UNTAGGED_PATH),
+              operations: untaggedOperations,
+              collapsed: !config.options?.expandAllTags,
+            }),
+          );
+        }
+
+        if (data.schema.components?.schemas?.length) {
+          categories.push({
+            type: "link" as const,
+            label: "Schemas",
+            href: joinUrl(basePath, versionParam, "~schemas"),
+          });
+        }
+
         return categories;
       } catch {
         return [];
       }
     },
-    getRoutes: () =>
-      [
-        {
-          async lazy() {
-            const { OpenApiRoute } = await import("./Route.js");
-            return {
-              element: <OpenApiRoute client={client} config={config} />,
-            };
-          },
-          children: [
-            {
-              path: basePath,
-              children: [
-                {
-                  index: true,
-                  async lazy() {
-                    const { OperationList } = await import(
-                      "./OperationList.js"
-                    );
-                    return { element: <OperationList /> };
-                  },
-                },
-              ],
-            },
-          ],
-        },
-      ] satisfies RouteObject[],
+    getRoutes: () => getRoutes({ basePath, config, client }),
   };
 };