zudoku 0.38.0 → 0.39.1

package/src/lib/core/ZudokuContext.ts

@@ -52,6 +52,7 @@ type Metadata = Partial<{
 }>;
 
 type Page = Partial<{
+  showPoweredBy: boolean;
   pageTitle?: string;
   logo?: {
     src: {

package/src/lib/oas/graphql/index.ts

@@ -97,7 +97,7 @@ const resolveExtensions = (obj: Record<string, any>) =>
 export const getAllTags = (
   schema: OpenAPIDocument,
   slugs: ReturnType<typeof getAllSlugs>["tags"],
-): Array<TagObject & { slug?: string }> => {
+): Array<Omit<TagObject, "name"> & { name?: string; slug?: string }> => {
   const rootTags = schema.tags ?? [];
   const operationTags = new Set(
     Object.values(schema.paths ?? {})
@@ -105,6 +105,12 @@ export const getAllTags = (
       .flatMap((op) => (op as OperationObject).tags ?? []),
   );
 
+  const hasUntaggedOperations = Object.values(schema.paths ?? {}).some((path) =>
+    Object.values(path ?? {}).some(
+      (op) => !(op as OperationObject).tags?.length,
+    ),
+  );
+
   return [
     // Keep root tags that are actually used in operations
     ...rootTags
@@ -114,6 +120,8 @@ export const getAllTags = (
     ...[...operationTags]
       .filter((tag) => !rootTags.some((rt) => rt.name === tag))
       .map((tag) => ({ name: tag, slug: slugs[tag] })),
+    // Add untagged operations if there are any
+    ...(hasUntaggedOperations ? [{ name: undefined, slug: undefined }] : []),
   ];
 };
 
@@ -181,38 +189,55 @@ export const getAllOperations = (
   return operations;
 };
 
-const SchemaTag = builder
-  .objectRef<
-    Omit<TagObject, "name"> & { name?: string; slug?: string }
-  >("SchemaTag")
-  .implement({
-    fields: (t) => ({
-      name: t.exposeString("name", { nullable: true }),
-      slug: t.exposeString("slug", { nullable: true }),
-      description: t.exposeString("description", { nullable: true }),
-      operations: t.field({
-        type: [OperationItem],
-        resolve: (parent, _args, ctx) => {
-          const rootTags = ctx.tags.map((tag) => tag.name);
-
-          return ctx.operations
-            .filter((item) =>
-              parent.name
-                ? item.tags?.includes(parent.name)
-                : item.tags?.length === 0 ||
-                  // If none of the tags are present in the root tags, then show them here
-                  item.tags?.every((tag) => !rootTags.includes(tag)),
-            )
-            .map((item) => ({ ...item, parentTag: parent.name }));
-        },
-      }),
-      extensions: t.field({
-        type: JSONObjectScalar,
-        resolve: (parent) => resolveExtensions(parent),
-        nullable: true,
-      }),
+const SchemaTag = builder.objectRef<
+  Omit<TagObject, "name"> & { name?: string; slug?: string }
+>("SchemaTag");
+
+SchemaTag.implement({
+  fields: (t) => ({
+    name: t.exposeString("name", { nullable: true }),
+    slug: t.exposeString("slug", { nullable: true }),
+    isUntagged: t.field({ type: "Boolean", resolve: (parent) => !parent.name }),
+    description: t.exposeString("description", { nullable: true }),
+    operations: t.field({
+      type: [OperationItem],
+      resolve: (parent, _args, ctx) => {
+        const rootTags = ctx.tags.map((tag) => tag.name);
+
+        return ctx.operations
+          .filter((item) =>
+            parent.name
+              ? item.tags?.includes(parent.name)
+              : item.tags?.length === 0 ||
+                // If none of the tags are present in the root tags, then show them here
+                item.tags?.every((tag) => !rootTags.includes(tag)),
+          )
+          .map((item) => ({ ...item, parentTag: parent.name }));
+      },
     }),
-  });
+    prev: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index - 1];
+      },
+    }),
+    next: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index + 1];
+      },
+    }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
+  }),
+});
 
 const ServerItem = builder.objectRef<ServerObject>("Server").implement({
   fields: (t) => ({
@@ -466,6 +491,43 @@ const OperationItem = builder
     }),
   });
 
+const SchemaItem = builder
+  .objectRef<{
+    name: string;
+    schema: SchemaObject;
+    extensions?: Record<string, any>;
+  }>("SchemaItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      schema: t.expose("schema", { type: JSONSchemaScalar }),
+      extensions: t.expose("extensions", {
+        type: JSONObjectScalar,
+        nullable: true,
+      }),
+    }),
+  });
+
+const Components = builder.objectRef<{
+  schemas?: Record<string, SchemaObject>;
+}>("Components");
+
+Components.implement({
+  fields: (t) => ({
+    schemas: t.field({
+      type: [SchemaItem],
+      resolve: (parent) => {
+        return Object.entries(parent.schemas ?? {}).map(([name, schema]) => ({
+          name,
+          schema,
+          extensions: resolveExtensions(schema),
+        }));
+      },
+      nullable: true,
+    }),
+  }),
+});
+
 const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   fields: (t) => ({
     openapi: t.string({ resolve: (root) => root.openapi }),
@@ -495,24 +557,30 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           methods: Object.keys(value!) as typeof HttpMethods,
         })),
     }),
-    tags: t.field({
+    tag: t.field({
+      type: SchemaTag,
       args: {
+        slug: t.arg.string(),
         name: t.arg.string(),
+        untagged: t.arg.boolean(),
       },
-      type: [SchemaTag],
-      resolve: (_root, args, ctx) => {
-        if (args.name) {
-          return ctx.tags.filter((tag) => tag.name === args.name);
+      nullable: true,
+      resolve: (_, args, ctx) => {
+        if (args.untagged) {
+          return ctx.tags.find((tag) => tag.name === undefined);
         }
-
-        // Append empty tag which will be used to display untagged operations
-        if (ctx.operations.some((op) => !op.tags?.length)) {
-          return [...ctx.tags, { name: undefined, slug: undefined }];
+        if (args.slug) {
+          return ctx.tags.find((tag) => tag.slug === args.slug);
+        }
+        if (args.name) {
+          return ctx.tags.find((tag) => tag.name === args.name);
         }
-
-        return ctx.tags;
       },
     }),
+    tags: t.field({
+      type: [SchemaTag],
+      resolve: (_root, _args, ctx) => ctx.tags,
+    }),
     operations: t.field({
       type: [OperationItem],
       args: {
@@ -522,7 +590,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         tag: t.arg.string(),
         untagged: t.arg.boolean(),
       },
-      resolve: (parent, args, ctx) =>
+      resolve: (_parent, args, ctx) =>
         ctx.operations.filter((op) => {
           return (
             (!args.operationId || op.operationId === args.operationId) &&
@@ -533,6 +601,11 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           );
         }),
     }),
+    components: t.field({
+      type: Components,
+      resolve: (root) => root.components,
+      nullable: true,
+    }),
     extensions: t.field({
       type: JSONObjectScalar,
       resolve: (root) => resolveExtensions(root),
@@ -553,7 +626,7 @@ builder.queryType({
         type: t.arg({ type: SchemaSource, required: true }),
         input: t.arg({ type: JSONScalar, required: true }),
       },
-      resolve: async (_, args, ctx) => {
+      resolve: async (_parent, args, ctx) => {
         if (args.type === "file" && typeof args.input === "string") {
           const loadSchema = ctx.schemaImports?.[args.input];
 

package/src/lib/oas/parser/dereference/index.ts

@@ -38,6 +38,8 @@ export const dereference = async (
         }
       } else {
         if ("$ref" in current && typeof current.$ref === "string") {
+          // Store the ref path before resolving
+          current.__$ref = current.$ref;
           for (const resolver of resolvers) {
             const resolved = await resolver(current.$ref);
             if (resolved) return await resolve(resolved, path);

package/src/lib/oas/parser/index.ts

@@ -3,11 +3,15 @@ import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
-type ReferenceObject = OpenAPIV3_1.ReferenceObject;
-type DeepOmitReference<T> = T extends ReferenceObject
+// Must be an interface (not a type) to allow merging with OpenAPI types with index signatures
+interface WithRef {
+  __$ref?: string;
+}
+
+type DeepOmitReference<T> = T extends OpenAPIV3_1.ReferenceObject
   ? never
   : T extends object
-    ? { [K in keyof T]: DeepOmitReference<T[K]> }
+    ? { [K in keyof T]: DeepOmitReference<T[K]> } & WithRef
     : T;
 
 export type OpenAPIDocument = DeepOmitReference<OpenAPIV3_1.Document>;
@@ -24,25 +28,6 @@ export type ServerObject = DeepOmitReference<OpenAPIV3_1.ServerObject>;
 
 export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
 
-// class ValidationError extends Error {
-//   constructor(public errors: OutputUnit[]) {
-//     super("Validation error");
-//   }
-// }
-
-// const getValidator = async (openApiVersion: string) => {
-//   if (openApiVersion.startsWith("3.0")) {
-//     const schema = (await import("./schemas/v3.0.json")) as any;
-//     return new Validator(schema, "4");
-//   }
-//   if (openApiVersion.startsWith("3.1")) {
-//     const schema = (await import("./schemas/v3.1.json")) as any;
-//     return new Validator(schema as any, "2020-12");
-//   }
-
-//   throw new Error(`Unsupported OpenAPI version: ${openApiVersion}`);
-// };
-
 const parseSchemaInput = async (
   schemaInput: unknown,
 ): Promise<JSONSchema & { openapi?: string }> => {
@@ -110,13 +95,6 @@ export const validate = async (schemaInput: unknown) => {
     throw new GraphQLError("OpenAPI version is not defined");
   }
 
-  // const validator = await getValidator(schema.openapi);
-  // const result = validator.validate(schema);
-  //
-  // if (!result.valid) {
-  //   throw new ValidationError(result.errors);
-  // }
-
   const dereferenced = await dereference(schema);
 
   return upgradeSchema(dereferenced);

package/src/lib/plugins/api-catalog/index.tsx

@@ -51,9 +51,22 @@ export const apiCatalogPlugin = ({
   items: ApiCatalogItem[];
   filterCatalogItems?: filterCatalogItems;
 }): ZudokuPlugin => {
+  const paths = Object.fromEntries(
+    categories.flatMap((category) =>
+      [undefined, ...category.tags].map((tag) => [
+        joinUrl(navigationId, tag ? getKey(category.label, tag) : undefined),
+        tag,
+      ]),
+    ),
+  );
+
   return {
-    getSidebar: async function Sidebar(path) {
-      if (!matchPath({ path: joinUrl(navigationId), end: false }, path)) {
+    getSidebar: async (currentPath) => {
+      const matches = Object.keys(paths).some((path) =>
+        matchPath(path, currentPath),
+      );
+
+      if (!matches) {
         return [];
       }
 
@@ -61,22 +74,19 @@ export const apiCatalogPlugin = ({
         type: "category" as const,
         label: category.label,
         collapsible: false,
-        items: category.tags.map((tag) => {
-          const tagPath = getKey(category.label, tag);
-          return {
-            type: "doc" as const,
-            id: joinUrl(navigationId, tagPath),
-            label: tag,
-            badge: {
-              label: String(
-                items.filter((api) =>
-                  api.categories.find((c) => c.tags.includes(tag)),
-                ).length,
-              ),
-              color: "outline" as const,
-            },
-          };
-        }),
+        items: category.tags.map((tag) => ({
+          type: "doc" as const,
+          id: joinUrl(navigationId, getKey(category.label, tag)),
+          label: tag,
+          badge: {
+            label: String(
+              items.filter((api) =>
+                api.categories.find((c) => c.tags.includes(tag)),
+              ).length,
+            ),
+            color: "outline" as const,
+          },
+        })),
       }));
 
       sidebar.unshift({
@@ -89,22 +99,17 @@ export const apiCatalogPlugin = ({
       return sidebar;
     },
     getRoutes: () =>
-      categories.flatMap((category) =>
-        [undefined, ...category.tags].map((tag) => ({
-          path: joinUrl(
-            navigationId,
-            tag ? getKey(category.label, tag) : undefined,
-          ),
-          element: (
-            <Catalog
-              label={label}
-              categoryLabel={tag}
-              items={items}
-              filterCatalogItems={filterCatalogItems}
-              categories={categories}
-            />
-          ),
-        })),
-      ),
+      Object.entries(paths).map(([path, tag]) => ({
+        path,
+        element: (
+          <Catalog
+            label={label}
+            categoryLabel={tag}
+            items={items}
+            filterCatalogItems={filterCatalogItems}
+            categories={categories}
+          />
+        ),
+      })),
   };
 };

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -2,17 +2,17 @@ import { useMDXComponents } from "@mdx-js/react";
 import slugify from "@sindresorhus/slugify";
 import { Helmet } from "@zudoku/react-helmet-async";
 import { type PropsWithChildren, useEffect } from "react";
-import { Link } from "react-router";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { ProseClasses } from "../../components/Markdown.js";
+import { Pagination } from "../../components/Pagination.js";
+import { Toc } from "../../components/navigation/Toc.js";
 import {
   useCurrentItem,
   usePrevNext,
 } from "../../components/navigation/utils.js";
 import type { MdxComponentsType } from "../../util/MdxComponents.js";
 import { cn } from "../../util/cn.js";
-import { Toc } from "./Toc.js";
 import { type MarkdownPluginDefaultOptions, type MDXImport } from "./index.js";
 
 declare global {
@@ -115,40 +115,10 @@ export const MdxPage = ({
         {!hidePager && (
           <>
             <hr />
-            <div className="not-prose flex flex-wrap items-center justify-between gap-2 lg:gap-8">
-              {prev ? (
-                <Link
-                  to={prev.id}
-                  className="flex flex-col items-stretch gap-2 flex-1 min-w-max border rounded px-6 py-4 text-start hover:border-primary/85 transition shadow-sm hover:shadow-md"
-                  title={prev.label}
-                >
-                  <div className="text-sm text-muted-foreground">
-                    ← Previous page
-                  </div>
-                  <div className="text-lg text-primary truncate">
-                    {prev.label}
-                  </div>
-                </Link>
-              ) : (
-                <div className="flex-1" />
-              )}
-              {next ? (
-                <Link
-                  to={next.id}
-                  className="flex flex-col items-stretch gap-2 flex-1 min-w-max border rounded px-6 py-4 text-end hover:border-primary/85 transition shadow-sm hover:shadow-md"
-                  title={next.label}
-                >
-                  <div className="text-sm text-muted-foreground">
-                    Next page →
-                  </div>
-                  <div className="text-lg text-primary truncate">
-                    {next.label}
-                  </div>
-                </Link>
-              ) : (
-                <div className="flex-1" />
-              )}
-            </div>
+            <Pagination
+              prev={prev ? { to: prev.id, label: prev.label } : undefined}
+              next={next ? { to: next.id, label: next.label } : undefined}
+            />
           </>
         )}
       </div>

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

@@ -90,7 +90,7 @@ export const ColorizedParam = ({
       {...{ [DATA_ATTR]: normalizedSlug }}
       className={cn(
         // This may not contain (inline-)flex or (inline-)block otherwise it breaks the browser's full text search
-        "relative rounded transition-all duration-100 rounded-lg",
+        "relative transition-all duration-100 rounded-lg",
         "border border-[--border-color] p-0.5 text-[--param-color] bg-[--background-color]",
         "data-[active=true]:border-[--param-color] data-[active=true]:shadow data-[active=true]:bottom-px",
         className,

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

@@ -18,6 +18,7 @@ import {
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown, ProseClasses } from "../../components/Markdown.js";
+import { Pagination } from "../../components/Pagination.js";
 import { useApiIdentities } from "../../components/context/ZudokuContext.js";
 import { cn } from "../../util/cn.js";
 import { Endpoint } from "./Endpoint.js";
@@ -25,6 +26,7 @@ import { OperationListItem } from "./OperationListItem.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/index.js";
+import { UNTAGGED_PATH } from "./index.js";
 import { useSelectedServer } from "./state.js";
 import { sanitizeMarkdownForMetatag } from "./util/sanitizeMarkdownForMetatag.js";
 
@@ -121,13 +123,21 @@ const OperationsForTagQuery = graphql(/* GraphQL */ `
       title
       url
       version
-      tags(name: $tag) {
+      tag(slug: $tag, untagged: $untagged) {
         name
         description
-      }
-      operations(tag: $tag, untagged: $untagged) {
-        slug
-        ...OperationsFragment
+        operations {
+          slug
+          ...OperationsFragment
+        }
+        next {
+          name
+          slug
+        }
+        prev {
+          name
+          slug
+        }
       }
     }
   }
@@ -156,8 +166,6 @@ export const OperationList = ({
   const summary = schema.summary;
   const description = schema.description;
   const navigate = useNavigate();
-  const operations = schema.operations;
-  const tagDescription = schema.tags.find((t) => t.name === tag)?.description;
 
   // This is to warmup (i.e. load the schema in the background) the schema on the client, if the page has been rendered on the server
   const warmupQuery = useCreateQuery(SchemaWarmupQuery, { input, type });
@@ -170,6 +178,10 @@ export const OperationList = ({
   // Prefetch for Playground
   useApiIdentities();
 
+  if (!schema.tag) return null;
+
+  const { operations, next, prev, description: tagDescription } = schema.tag;
+
   // The summary property is preferable here as it is a short description of
   // the API, whereas the description property is typically longer and supports
   // commonmark formatting, making it ill-suited for use in the meta description
@@ -187,6 +199,16 @@ export const OperationList = ({
     options?.showVersionSelect === "always" ||
     (hasMultipleVersions && options?.showVersionSelect !== "hide");
 
+  const paginationProps = {
+    prev: prev?.name ? { to: `../${prev.slug}`, label: prev.name } : undefined,
+    next: next
+      ? {
+          to: `../${next.slug ?? UNTAGGED_PATH}`,
+          label: next.name ?? "Other endpoints",
+        }
+      : undefined,
+  };
+
   return (
     <div
       className="pt-[--padding-content-top]"
@@ -194,7 +216,7 @@ export const OperationList = ({
       data-pagefind-meta="section:openapi"
     >
       <Helmet>
-        <title>{[tag, title].filter(Boolean).join(" - ")}</title>
+        <title>{[schema.tag.name, title].filter(Boolean).join(" - ")}</title>
         {metaDescription && (
           <meta name="description" content={metaDescription} />
         )}
@@ -202,7 +224,7 @@ export const OperationList = ({
       <div className="mb-8">
         <Collapsible className="w-full">
           <div className="flex flex-col gap-y-4 sm:flex-row justify-around items-start sm:items-end">
-            <div className="flex-1">
+            <div className="flex flex-col flex-1 gap-2">
               <CategoryHeading>{title}</CategoryHeading>
               <Heading
                 level={1}
@@ -210,7 +232,7 @@ export const OperationList = ({
                 registerSidebarAnchor
                 className="mb-0"
               >
-                {tag ?? "Other endpoints"}
+                {schema.tag.name ?? "Other endpoints"}
                 {showVersions && (
                   <span className="text-xl text-muted-foreground ml-1.5">
                     {" "}
@@ -218,6 +240,7 @@ export const OperationList = ({
                   </span>
                 )}
               </Heading>
+              <Endpoint />
             </div>
             <div className="flex flex-col gap-4 sm:items-end">
               {showVersions && (
@@ -240,7 +263,7 @@ export const OperationList = ({
               )}
               {schema.description && (
                 <CollapsibleTrigger className="flex items-center gap-1 text-sm font-medium text-muted-foreground group">
-                  <span>Schema description</span>
+                  <span>API information</span>
 
                   <ChevronsUpDownIcon
                     className="group-data-[state=open]:hidden translate-y-px"
@@ -282,11 +305,8 @@ export const OperationList = ({
         )}
       </div>
       <hr />
-      <div className="my-4 flex items-center justify-end gap-4">
-        <Endpoint />
-      </div>
       {/* px, -mx is so that `content-visibility` doesn't cut off overflown heading anchor links '#' */}
-      <div className="px-6 -mx-6 [content-visibility:auto]">
+      <div className="px-6 mt-6 -mx-6 [content-visibility:auto]">
         {operations.map((fragment) => (
           <OperationListItem
             serverUrl={selectedServer}
@@ -294,6 +314,7 @@ export const OperationList = ({
             operationFragment={fragment}
           />
         ))}
+        <Pagination {...paginationProps} />
       </div>
     </div>
   );

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

@@ -100,13 +100,18 @@ export const OperationListItem = ({
             <div className="mt-4 flex flex-col gap-4">
               <Heading
                 level={3}
-                className="capitalize"
+                className="capitalize flex items-center gap-2"
                 id={`${operation.slug}/request-body`}
               >
                 {operation.summary && (
                   <VisuallyHidden>{operation.summary} &rsaquo; </VisuallyHidden>
                 )}
-                Request Body
+                Request Body{" "}
+                {operation.requestBody?.required === false ? (
+                  <Badge variant="muted">optional</Badge>
+                ) : (
+                  ""
+                )}
               </Heading>
               <SchemaView schema={schema} />
             </div>

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

@@ -6,6 +6,7 @@ import type { ParameterGroup } from "./OperationListItem.js";
 import { ParamInfos } from "./ParamInfos.js";
 import { EnumValues } from "./components/EnumValues.js";
 import { SelectOnClick } from "./components/SelectOnClick.js";
+import { SchemaExampleAndDefault } from "./schema/SchemaExampleAndDefault.js";
 
 const getParameterSchema = (
   parameter: ParameterListItemResult,
@@ -72,6 +73,7 @@ export const ParameterListItem = ({
       ) : (
         paramSchema.enum && <EnumValues values={paramSchema.enum} />
       )}
+      <SchemaExampleAndDefault schema={paramSchema} />
     </li>
   );
 };