zudoku 0.65.2 → 0.66.0

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

@@ -18,9 +18,12 @@ import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { useApiIdentities } from "../../components/context/ZudokuContext.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { Pagination } from "../../components/Pagination.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
+import { DownloadSchemaButton } from "./DownloadSchemaButton.js";
 import { Endpoint } from "./Endpoint.js";
 import { graphql } from "./graphql/index.js";
 import { UNTAGGED_PATH } from "./index.js";
@@ -155,7 +158,7 @@ export const OperationList = ({
   tag?: string;
   untagged?: boolean;
 }) => {
-  const { input, type, versions, version, options } = useOasConfig();
+  const { path, input, type, versions, version, options } = useOasConfig();
   const { tag: tagFromParams } = useParams<"tag">();
   const query = useCreateQuery(OperationsForTagQuery, {
     input,
@@ -244,12 +247,20 @@ export const OperationList = ({
   const tagTitle = schema.tag.extensions?.["x-displayName"] ?? schema.tag.name;
   const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
 
+  const downloadUrl =
+    typeof input === "string"
+      ? type === "url"
+        ? input
+        : joinUrl(path, version, input.split("/").pop())
+      : undefined;
+
   return (
     <div
       className="pt-(--padding-content-top)"
       data-pagefind-filter="section:openapi"
       data-pagefind-meta="section:openapi"
     >
+      <PagefindSearchMeta name="category">{title}</PagefindSearchMeta>
       <Helmet>
         {helmetTitle && <title>{helmetTitle}</title>}
         {metaDescription && (
@@ -262,7 +273,7 @@ export const OperationList = ({
           className="w-full"
           defaultOpen={options?.expandApiInformation}
         >
-          <div className="flex flex-col gap-y-4 sm:flex-row justify-around items-start sm:items-end">
+          <div className="flex flex-col gap-4 sm:flex-row justify-around items-start sm:items-end">
             <div className="flex flex-col flex-1 gap-2">
               <CategoryHeading>{title}</CategoryHeading>
               <Heading
@@ -282,25 +293,32 @@ export const OperationList = ({
               <Endpoint />
             </div>
             <div className="flex flex-col gap-4 sm:items-end">
-              {showVersions && (
-                <Select
-                  // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-                  onValueChange={(version) => navigate(versions[version]!)}
-                  defaultValue={version}
-                  disabled={!hasMultipleVersions}
-                >
-                  <SelectTrigger className="w-[180px]">
-                    <SelectValue placeholder="Select version" />
-                  </SelectTrigger>
-                  <SelectContent>
-                    {Object.entries(versions).map(([version]) => (
-                      <SelectItem key={version} value={version}>
-                        {version}
-                      </SelectItem>
-                    ))}
-                  </SelectContent>
-                </Select>
-              )}
+              <div className="flex gap-2 items-center">
+                {showVersions && (
+                  <Select
+                    onValueChange={(version) =>
+                      // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
+                      navigate(versions[version]!.path)
+                    }
+                    defaultValue={version}
+                    disabled={!hasMultipleVersions}
+                  >
+                    <SelectTrigger className="w-[180px]" size="sm">
+                      <SelectValue placeholder="Select version" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {Object.entries(versions).map(([version, { label }]) => (
+                        <SelectItem key={version} value={version}>
+                          {label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                )}
+                {options?.schemaDownload?.enabled && downloadUrl && (
+                  <DownloadSchemaButton downloadUrl={downloadUrl} />
+                )}
+              </div>
               {schema.description && (
                 <CollapsibleTrigger className="flex items-center gap-1 text-sm font-medium text-muted-foreground group">
                   <span>API information</span>

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

@@ -1,9 +1,9 @@
-import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { useState } from "react";
 import { Badge } from "zudoku/ui/Badge.js";
 import { Separator } from "zudoku/ui/Separator.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { cn } from "../../util/cn.js";
 import { groupBy } from "../../util/groupBy.js";
 import { renderIf } from "../../util/renderIf.js";
@@ -134,9 +134,9 @@ export const OperationListItem = ({
                     id={`${operation.slug}/request-body`}
                   >
                     {operation.summary && (
-                      <VisuallyHidden>
+                      <PagefindSearchMeta>
                         {operation.summary} &rsaquo;{" "}
-                      </VisuallyHidden>
+                      </PagefindSearchMeta>
                     )}
                     Request Body{" "}
                     {operation.requestBody?.required === false ? (
@@ -154,9 +154,9 @@ export const OperationListItem = ({
               <>
                 <Heading level={3} id={`${operation.slug}/responses`}>
                   {operation.summary && (
-                    <VisuallyHidden>
+                    <PagefindSearchMeta>
                       {operation.summary} &rsaquo;{" "}
-                    </VisuallyHidden>
+                    </PagefindSearchMeta>
                   )}
                   Responses
                 </Heading>

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

@@ -35,14 +35,14 @@ export const ParameterList = ({
       <Frame>
         <FramePanel className="p-0!">
           <ItemGroup className="overflow-clip">
-            {sortedParameters.map((parameter) => (
+            {sortedParameters.map((parameter, index) => (
               <Fragment key={`${parameter.name}-${parameter.in}`}>
+                {index > 0 && <ItemSeparator />}
                 <ParameterListItem
                   parameter={parameter}
                   id={id}
                   group={group}
                 />
-                <ItemSeparator />
               </Fragment>
             ))}
           </ItemGroup>

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

@@ -1,4 +1,4 @@
-import { ChevronsDownUpIcon, ChevronsUpDownIcon } from "lucide-react";
+import { ChevronsDownUpIcon, ChevronsUpDownIcon, InfoIcon } from "lucide-react";
 import { useEffect, useState } from "react";
 import { Button } from "zudoku/components";
 import {
@@ -7,6 +7,12 @@ import {
   CollapsibleTrigger,
 } from "zudoku/ui/Collapsible.js";
 import { NativeSelect, NativeSelectOption } from "zudoku/ui/NativeSelect.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "zudoku/ui/Tooltip.js";
 import type { ResponseItem } from "./graphql/graphql.js";
 import * as SidecarBox from "./SidecarBox.js";
 import { SidecarExamples } from "./SidecarExamples.js";
@@ -16,11 +22,13 @@ export const ResponsesSidecarBox = ({
   selectedResponse,
   isOnScreen,
   shouldLazyHighlight,
+  isGenerated,
 }: {
   responses: ResponseItem[];
   selectedResponse?: string;
   isOnScreen: boolean;
   shouldLazyHighlight?: boolean;
+  isGenerated?: boolean;
 }) => {
   const [internalSelectedResponse, setInternalSelectedResponse] = useState(
     selectedResponse ?? responses[0]?.statusCode,
@@ -57,8 +65,20 @@ export const ResponsesSidecarBox = ({
               </Button>
             </CollapsibleTrigger>
             Example Responses
+            {isGenerated && (
+              <TooltipProvider>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <InfoIcon size={13} />
+                  </TooltipTrigger>
+                  <TooltipContent>
+                    This example is auto-generated from the schema.
+                  </TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+            )}
           </div>
-          <div className="group-data-[state=closed]/collapsible:hidden">
+          <div className="group-data-[state=closed]/collapsible:invisible">
             <NativeSelect
               className="text-xs h-fit py-1 -my-1 bg-background"
               value={internalSelectedResponse}

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

@@ -16,6 +16,7 @@ import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
 import { Toc } from "../../components/navigation/Toc.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/gql.js";
@@ -70,6 +71,9 @@ export function SchemaList() {
       data-pagefind-filter="section:openapi"
       data-pagefind-meta="section:openapi"
     >
+      <PagefindSearchMeta name="category">
+        {data.schema.title}
+      </PagefindSearchMeta>
       <Helmet>
         <title>Schemas {showVersions ? version : ""}</title>
         <meta name="description" content="List of schemas used by the API." />

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

@@ -267,7 +267,7 @@ export const Sidecar = ({
         />
       ) : null}
 
-      {hasResponseExamples && (
+      {hasResponseExamples ? (
         <ResponsesSidecarBox
           isOnScreen={isOnScreen}
           shouldLazyHighlight={shouldLazyHighlight}
@@ -286,6 +286,22 @@ export const Sidecar = ({
                 : response.content,
           }))}
         />
+      ) : (
+        <ResponsesSidecarBox
+          isGenerated
+          isOnScreen={isOnScreen}
+          shouldLazyHighlight={shouldLazyHighlight}
+          selectedResponse={selectedResponse}
+          responses={operation.responses.map((response) => ({
+            ...response,
+            content: response.content?.map((content) => ({
+              ...content,
+              examples: content.schema
+                ? [{ name: "", value: generateSchemaExample(content.schema) }]
+                : content.examples,
+            })),
+          }))}
+        />
       )}
     </aside>
   );

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

@@ -13,7 +13,7 @@ import type { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
 import { createNavigationCategory } from "./util/createNavigationCategory.js";
-import { getRoutes, getVersions } from "./util/getRoutes.js";
+import { getRoutes, getVersionMetadata } from "./util/getRoutes.js";
 
 export const GetNavigationOperationsQuery = graphql(`
   query GetNavigationOperations($input: JSON!, $type: SchemaType!) {
@@ -54,14 +54,19 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
   return {
     getHead: () => {
       if (config.type === "url" && !config.skipPreload) {
-        return (
+        const urls = Array.isArray(config.input)
+          ? config.input.map((v) => v.input)
+          : [config.input];
+
+        return urls.map((url) => (
           <link
+            key={url}
+            href={url}
             rel="preload"
-            href={config.input}
             as="fetch"
             crossOrigin="anonymous"
           />
-        );
+        ));
       }
 
       if (config.server) {
@@ -111,10 +116,14 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
 
       try {
         const versionParam = match?.params.version;
-        const version = versionParam ?? getVersions(config).at(0);
+        const { versions } = getVersionMetadata(config);
+        const version = versionParam ?? versions.at(0);
         const { type } = config;
-        // biome-ignore lint/style/noNonNullAssertion: version is guaranteed to be defined
-        const input = type === "file" ? config.input[version!] : config.input;
+
+        const input = Array.isArray(config.input)
+          ? (config.input.find((v) => v.path === version)?.input ??
+            config.input[0]?.input)
+          : config.input;
 
         const query = createQuery(client, GetNavigationOperationsQuery, {
           type,

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

@@ -5,15 +5,21 @@ import type { OperationsFragmentFragment } from "./graphql/graphql.js";
 
 type DynamicInput = () => Promise<unknown>;
 
+export type VersionedInput<T> = Array<{
+  path: string;
+  label?: string;
+  input: T;
+}>;
+
 type OasSource =
-  | { type: "url"; input: string }
-  | { type: "file"; input: { [version: string]: DynamicInput } }
+  | { type: "url"; input: string | VersionedInput<string> }
+  | { type: "file"; input: VersionedInput<DynamicInput> }
   | { type: "raw"; input: string };
 
-export type ContextOasSource =
-  | { type: "url"; input: string }
-  | { type: "file"; input: DynamicInput }
-  | { type: "raw"; input: string };
+export type ContextOasSource = {
+  type: "url" | "file" | "raw";
+  input: string | DynamicInput;
+};
 
 type Example = {
   name: string;
@@ -66,6 +72,9 @@ type BaseOasConfig = {
     showVersionSelect?: "always" | "if-available" | "hide";
     expandAllTags?: boolean;
     expandApiInformation?: boolean;
+    schemaDownload?: {
+      enabled: boolean;
+    };
     transformExamples?: TransformExamplesFn;
     generateCodeSnippet?: GenerateCodeSnippetFn;
   };
@@ -76,5 +85,5 @@ export type OasPluginConfig = BaseOasConfig & OasSource;
 export type OasPluginContext = BaseOasConfig &
   ContextOasSource & {
     version?: string;
-    versions: Record<string, string>;
+    versions: Record<string, { path: string; label: string }>;
   };

package/src/lib/plugins/openapi/playground/Playground.tsx

@@ -247,7 +247,11 @@ export const Playground = ({
 
       const request = new Request(
         createUrl(server ?? selectedServer, url, data),
-        { method, headers, body },
+        {
+          method,
+          headers,
+          body: ["GET", "HEAD"].includes(method.toUpperCase()) ? null : body,
+        },
       );
 
       if (data.identity !== NO_IDENTITY) {
@@ -383,7 +387,7 @@ export const Playground = ({
             value={selectedServer}
             defaultValue={selectedServer}
           >
-            <SelectTrigger className="p-0 border-none flex-row-reverse bg-transparent text-xs gap-0.5 h-auto translate-y-[4px]">
+            <SelectTrigger className="p-0 h-fit shadow-none border-none flex-row-reverse bg-transparent text-xs gap-0.5 translate-y-[4px]">
               <SelectValue />
             </SelectTrigger>
             <SelectContent>

package/src/lib/plugins/openapi/schema/SchemaView.tsx

@@ -17,7 +17,7 @@ import { ParamInfos } from "../ParamInfos.js";
 import { SchemaExampleAndDefault } from "./SchemaExampleAndDefault.js";
 import { SchemaPropertyItem } from "./SchemaPropertyItem.js";
 import { UnionView } from "./UnionView.js";
-import { isBasicType } from "./utils.js";
+import { isArrayType, isBasicType } from "./utils.js";
 
 const renderMarkdown = (content?: string) =>
   content && (
@@ -91,10 +91,20 @@ export const SchemaView = ({
     return renderBasicSchema(schema, cardHeader, embedded);
   }
 
-  if (schema.type === "array" && typeof schema.items === "object") {
-    return <SchemaView schema={schema.items} cardHeader={cardHeader} />;
+  if (isArrayType(schema) && typeof schema.items === "object") {
+    const wrappedSchema: SchemaObject = {
+      type: "object",
+      properties: { "": schema },
+    };
+
+    return (
+      <SchemaView schema={wrappedSchema} cardHeader={cardHeader} defaultOpen />
+    );
   }
 
+  const additionalObjectProperties = typeof schema.additionalProperties ===
+    "object" && <SchemaView schema={schema.additionalProperties} embedded />;
+
   if (schema.type === "object") {
     const groupedProperties = groupBy(
       Object.entries(schema.properties ?? {}),
@@ -106,32 +116,31 @@ export const SchemaView = ({
             : "optional";
       },
     );
+
     const groupNames = ["required", "optional", "deprecated"] as const;
+    const groups = groupNames.flatMap((group) => {
+      const properties = groupedProperties[group];
+      return properties ? { group, properties } : [];
+    });
 
-    const additionalObjectProperties = typeof schema.additionalProperties ===
-      "object" && <SchemaView schema={schema.additionalProperties} embedded />;
-
-    const itemsList = groupNames.map(
-      (group, index) =>
-        groupedProperties[group] && (
-          <Fragment key={group}>
-            {index > 0 && <ItemSeparator />}
-            <ItemGroup className="overflow-clip">
-              {groupedProperties[group].map(([name, schema], index) => (
-                <Fragment key={name}>
-                  {index > 0 && <ItemSeparator />}
-                  <SchemaPropertyItem
-                    name={name}
-                    schema={schema}
-                    group={group}
-                    defaultOpen={defaultOpen}
-                  />
-                </Fragment>
-              ))}
-            </ItemGroup>
-          </Fragment>
-        ),
-    );
+    const itemsList = groups.map(({ group, properties }, index) => (
+      <Fragment key={group}>
+        {index > 0 && <ItemSeparator />}
+        <ItemGroup className="overflow-clip">
+          {properties.map(([name, schema], index) => (
+            <Fragment key={name}>
+              {index > 0 && <ItemSeparator />}
+              <SchemaPropertyItem
+                name={name}
+                schema={schema}
+                group={group}
+                defaultOpen={defaultOpen}
+              />
+            </Fragment>
+          ))}
+        </ItemGroup>
+      </Fragment>
+    ));
 
     if (embedded) {
       return itemsList;

package/src/lib/plugins/openapi/schema/utils.ts

@@ -1,5 +1,8 @@
 import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
-import type { SchemaObject } from "../../../oas/parser/index.js";
+import type {
+  ArraySchemaObject,
+  SchemaObject,
+} from "../../../oas/parser/index.js";
 
 export const isBasicType = (
   type: unknown,
@@ -8,7 +11,7 @@ export const isBasicType = (
     ["string", "number", "boolean", "integer", "null"].includes(type)) ||
   (Array.isArray(type) && type.every(isBasicType));
 
-export const isArrayType = (value: SchemaObject) =>
+export const isArrayType = (value: SchemaObject): value is ArraySchemaObject =>
   value.type === "array" ||
   // schema.type might be an array of types, so we need to check if "array" is one of them
   (Array.isArray(value.type) && value.type.includes("array"));

package/src/lib/plugins/openapi/util/getRoutes.tsx

@@ -148,8 +148,18 @@ const createVersionRoutes = (
   ];
 };
 
-export const getVersions = (config: OasPluginConfig) =>
-  config.type === "file" ? Object.keys(config.input) : [];
+export const getVersionMetadata = (config: OasPluginConfig) => {
+  if (config.type === "raw" || !Array.isArray(config.input)) {
+    return { versions: [], labels: {} };
+  }
+
+  return {
+    versions: config.input.map((v) => v.path),
+    labels: Object.fromEntries(
+      config.input.map((v) => [v.path, v.label ?? v.path]),
+    ),
+  };
+};
 
 export const getRoutes = ({
   basePath,
@@ -161,10 +171,33 @@ export const getRoutes = ({
   basePath: string;
 }): RouteObject[] => {
   const tagPages = config.tagPages;
+  const { versions } = getVersionMetadata(config);
 
   // If the config does not provide tag pages the catch-all
   // route handles all operations on a single page
   if (!tagPages) {
+    // If there are versions, create versioned routes even without tag pages
+    if (versions.length > 0) {
+      const versionsInPath =
+        versions.length > 1 ? [undefined, ...versions] : [undefined];
+
+      return versionsInPath.map((version) => {
+        const versionPath = joinUrl(basePath, version);
+        return createOasProvider({
+          basePath,
+          version,
+          routePath: versionPath,
+          routes: [
+            createNonTagPagesRoute({ path: `${versionPath}/:tag?` }),
+            ...createAdditionalRoutes(versionPath),
+          ],
+          client,
+          config,
+        });
+      });
+    }
+
+    // No versions, single route
     return [
       createOasProvider({
         basePath,
@@ -179,7 +212,6 @@ export const getRoutes = ({
     ];
   }
 
-  const versions = getVersions(config);
   // The latest version always is added as index path
   const versionsInPath =
     versions.length > 1 ? [undefined, ...versions] : [undefined];