zudoku 0.0.0-feat-openapi-docs-redesign.dab3fc6a → 0.0.0-feat-navigation-at-property.z8cd07fa5

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,21 +65,35 @@ 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:invisible">
+            <NativeSelect
+              className="text-xs h-fit py-1 -my-1 bg-background"
+              value={internalSelectedResponse}
+              onChange={(e) => setInternalSelectedResponse(e.target.value)}
+            >
+              {responses.map((response) => (
+                <NativeSelectOption
+                  key={response.statusCode}
+                  value={response.statusCode}
+                >
+                  {response.statusCode}
+                </NativeSelectOption>
+              ))}
+            </NativeSelect>
           </div>
-          <NativeSelect
-            className="text-xs h-fit py-1 -my-1 bg-background"
-            value={internalSelectedResponse}
-            onChange={(e) => setInternalSelectedResponse(e.target.value)}
-          >
-            {responses.map((response) => (
-              <NativeSelectOption
-                key={response.statusCode}
-                value={response.statusCode}
-              >
-                {response.statusCode}
-              </NativeSelectOption>
-            ))}
-          </NativeSelect>
         </SidecarBox.Head>
         <CollapsibleContent>
           <SidecarExamples

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

@@ -149,10 +149,10 @@ export const Sidecar = ({
       selectedServer,
       exampleBody: currentExampleCode
         ? {
-            mimeType: "application/json",
+            mimeType: selectedContent?.mediaType ?? "application/json",
             text: JSON.stringify(currentExampleCode, null, 2),
           }
-        : { mimeType: "application/json" },
+        : { mimeType: selectedContent?.mediaType ?? "application/json" },
     });
 
     return getConverted(snippet, selectedLang);
@@ -161,6 +161,7 @@ export const Sidecar = ({
     operation,
     selectedServer,
     selectedLang,
+    selectedContent,
     options,
     auth,
     context,
@@ -267,7 +268,7 @@ export const Sidecar = ({
         />
       ) : null}
 
-      {hasResponseExamples && (
+      {hasResponseExamples ? (
         <ResponsesSidecarBox
           isOnScreen={isOnScreen}
           shouldLazyHighlight={shouldLazyHighlight}
@@ -286,6 +287,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,23 @@ import type { OperationsFragmentFragment } from "./graphql/graphql.js";
 
 type DynamicInput = () => Promise<unknown>;
 
+export type VersionedInput<T> = Array<{
+  path: string;
+  version?: string;
+  downloadUrl?: 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 +74,9 @@ type BaseOasConfig = {
     showVersionSelect?: "always" | "if-available" | "hide";
     expandAllTags?: boolean;
     expandApiInformation?: boolean;
+    schemaDownload?: {
+      enabled: boolean;
+    };
     transformExamples?: TransformExamplesFn;
     generateCodeSnippet?: GenerateCodeSnippetFn;
   };
@@ -76,5 +87,8 @@ export type OasPluginConfig = BaseOasConfig & OasSource;
 export type OasPluginContext = BaseOasConfig &
   ContextOasSource & {
     version?: string;
-    versions: Record<string, string>;
+    versions: Record<
+      string,
+      { path: string; label: string; downloadUrl?: string }
+    >;
   };

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

@@ -227,7 +227,7 @@ export const Playground = ({
 
       switch (data.bodyMode) {
         case "file":
-          body = data.file ?? undefined;
+          body = data.file || undefined;
           headers.delete("Content-Type");
           break;
         case "multipart": {
@@ -241,13 +241,17 @@ export const Playground = ({
           break;
         }
         default:
-          body = data.body ?? undefined;
+          body = data.body || undefined;
           break;
       }
 
       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/playground/fileUtils.ts

@@ -4,6 +4,10 @@ export function isBinaryContentType(contentType: string) {
   );
 }
 
+export function isAudioContentType(contentType: string) {
+  return /^audio\//i.test(contentType);
+}
+
 export const extractFileName = (
   headers: Array<[string, string]>,
   url: string,

package/src/lib/plugins/openapi/playground/result-panel/AudioPlayer.tsx

@@ -0,0 +1,50 @@
+import { DownloadIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+import { Button } from "zudoku/ui/Button.js";
+import { humanFileSize } from "../../../../util/humanFileSize.js";
+
+export const AudioPlayer = ({
+  blob,
+  fileName,
+  size,
+  onDownload,
+}: {
+  blob: Blob;
+  fileName: string;
+  size: number;
+  onDownload: () => void;
+}) => {
+  const [audioUrl, setAudioUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    const url = URL.createObjectURL(blob);
+    setAudioUrl(url);
+
+    return () => {
+      URL.revokeObjectURL(url);
+    };
+  }, [blob]);
+
+  if (!audioUrl) {
+    return (
+      <div className="p-4 text-center">
+        <div className="text-sm text-muted-foreground">Loading audio...</div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4 text-center">
+      <div className="flex flex-col items-center gap-4">
+        {/* biome-ignore lint/a11y/useMediaCaption: API response audio cannot have predefined captions */}
+        <audio controls src={audioUrl} className="w-full max-w-md">
+          Your browser does not support the audio element.
+        </audio>
+        <Button onClick={onDownload} className="flex items-center gap-2">
+          <DownloadIcon className="h-4 w-4" />
+          Download {fileName} ({humanFileSize(size)})
+        </Button>
+      </div>
+    </div>
+  );
+};

package/src/lib/plugins/openapi/playground/result-panel/ResponseTab.tsx

@@ -32,6 +32,8 @@ import {
   CollapsibleHeader,
   CollapsibleHeaderTrigger,
 } from "../CollapsibleHeader.js";
+import { isAudioContentType } from "../fileUtils.js";
+import { AudioPlayer } from "./AudioPlayer.js";
 import { convertToTypes } from "./convertToTypes.js";
 
 const mimeTypeToLanguage = (mimeType: string) => {
@@ -50,9 +52,14 @@ const mimeTypeToLanguage = (mimeType: string) => {
   )?.[1];
 };
 
+const getContentType = (headers: Array<[string, string]>) => {
+  return (
+    headers.find(([key]) => key.toLowerCase() === "content-type")?.[1] || ""
+  );
+};
+
 const detectLanguage = (headers: Array<[string, string]>) => {
-  const contentType =
-    headers.find(([key]) => key.toLowerCase() === "content-type")?.[1] || "";
+  const contentType = getContentType(headers);
   return mimeTypeToLanguage(contentType);
 };
 
@@ -293,23 +300,32 @@ export const ResponseTab = ({
       </div>
       <div className="flex-1">
         {isBinary ? (
-          <div className="p-4 text-center">
-            <div className="flex flex-col items-center gap-4">
-              <div className="text-lg font-semibold">Binary Content</div>
-              <div className="text-sm text-muted-foreground">
-                This response contains binary data that cannot be displayed as
-                text.
+          blob && isAudioContentType(getContentType(headers)) ? (
+            <AudioPlayer
+              blob={blob}
+              fileName={fileName ?? "audio"}
+              size={size}
+              onDownload={handleDownload}
+            />
+          ) : (
+            <div className="p-4 text-center">
+              <div className="flex flex-col items-center gap-4">
+                <div className="text-lg font-semibold">Binary Content</div>
+                <div className="text-sm text-muted-foreground">
+                  This response contains binary data that cannot be displayed as
+                  text.
+                </div>
+                <Button
+                  onClick={handleDownload}
+                  className="flex items-center gap-2"
+                  disabled={!blob}
+                >
+                  <DownloadIcon className="h-4 w-4" />
+                  Download {fileName || "file"} ({humanFileSize(size)})
+                </Button>
               </div>
-              <Button
-                onClick={handleDownload}
-                className="flex items-center gap-2"
-                disabled={!blob}
-              >
-                <DownloadIcon className="h-4 w-4" />
-                Download {fileName || "file"} ({humanFileSize(size)})
-              </Button>
             </div>
-          </div>
+          )
         ) : (
           <SyntaxHighlight
             className="text-xs flex-1"

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

@@ -3,6 +3,7 @@ import { Fragment } from "react";
 import {
   Frame,
   FrameDescription,
+  FrameFooter,
   FrameHeader,
   FramePanel,
 } from "zudoku/ui/Frame.js";
@@ -16,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 && (
@@ -90,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 ?? {}),
@@ -105,43 +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 additionalProperties =
-      typeof schema.additionalProperties === "object" ? (
-        <SchemaView schema={schema.additionalProperties} embedded />
-      ) : schema.additionalProperties === true ? (
-        <div className="text-sm p-4 flex items-center gap-1">
-          <span>Additional properties are allowed</span>
-          <a
-            className="p-0.5 -m-0.5"
-            href="https://swagger.io/docs/specification/v3_0/data-models/dictionaries/"
-            rel="noopener noreferrer"
-            target="_blank"
-          >
-            <InfoIcon size={14} />
-          </a>
-        </div>
-      ) : null;
-
-    const itemsList = groupNames.map(
-      (group) =>
-        groupedProperties[group] && (
-          <ItemGroup key={group} className="overflow-clip">
-            {groupedProperties[group].map(([name, schema]) => (
-              <Fragment key={name}>
-                <SchemaPropertyItem
-                  name={name}
-                  schema={schema}
-                  group={group}
-                  defaultOpen={defaultOpen}
-                />
-                <ItemSeparator />
-              </Fragment>
-            ))}
-          </ItemGroup>
-        ),
-    );
+    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;
@@ -155,11 +154,25 @@ export const SchemaView = ({
             <FrameDescription>{schema.description}</FrameDescription>
           </FrameHeader>
         )}
-
-        <FramePanel className="p-0!">
-          {itemsList}
-          {additionalProperties}
-        </FramePanel>
+        {(itemsList.length > 0 || additionalObjectProperties) && (
+          <FramePanel className="p-0!">
+            {itemsList}
+            {additionalObjectProperties}
+          </FramePanel>
+        )}
+        {schema.additionalProperties === true && (
+          <FrameFooter>
+            <a
+              className="text-sm flex items-center gap-1 hover:underline"
+              href="https://swagger.io/docs/specification/v3_0/data-models/dictionaries/"
+              rel="noopener noreferrer"
+              target="_blank"
+            >
+              Additional properties are allowed
+              <InfoIcon size={14} />
+            </a>
+          </FrameFooter>
+        )}
       </Frame>
     );
   }

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

@@ -1,5 +1,11 @@
-import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
-import type { SchemaObject } from "../../../oas/parser/index.js";
+import {
+  CIRCULAR_REF,
+  SCHEMA_REF_PREFIX,
+} from "../../../oas/graphql/circular.js";
+import type {
+  ArraySchemaObject,
+  SchemaObject,
+} from "../../../oas/parser/index.js";
 
 export const isBasicType = (
   type: unknown,
@@ -8,7 +14,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"));
@@ -22,7 +28,8 @@ export const isComplexType = (value?: SchemaObject) =>
       (!value.items.type || value.items.type === "object")));
 
 export const isCircularRef = (schema: unknown): schema is string =>
-  typeof schema === "string" && schema.startsWith(CIRCULAR_REF);
+  typeof schema === "string" &&
+  (schema.startsWith(CIRCULAR_REF) || schema.startsWith(SCHEMA_REF_PREFIX));
 
 export const isArrayCircularRef = (
   schema: SchemaObject,
@@ -31,5 +38,12 @@ export const isArrayCircularRef = (
 
 export const extractCircularRefInfo = (
   ref?: string | SchemaObject,
-): string | undefined =>
-  typeof ref === "string" ? ref.split(":")[1] : undefined;
+): string | undefined => {
+  if (typeof ref !== "string") return undefined;
+
+  if (ref.startsWith(SCHEMA_REF_PREFIX)) {
+    return ref.slice(SCHEMA_REF_PREFIX.length).split("/").pop();
+  }
+
+  return ref.split(":")[1];
+};

package/src/lib/plugins/openapi/util/createHttpSnippet.ts

@@ -1,6 +1,23 @@
 import { HTTPSnippet } from "@zudoku/httpsnippet";
 import type { OperationsFragmentFragment } from "../graphql/graphql.js";
 
+const toFormDataParams = (text?: string) => {
+  const stringify = (v: unknown) =>
+    typeof v === "string" ? v : JSON.stringify(v);
+
+  try {
+    const obj = text && JSON.parse(text);
+    if (typeof obj !== "object" || !obj) return [];
+
+    return Object.entries(obj).flatMap(([name, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      return values.map((v) => ({ name, value: stringify(v) }));
+    });
+  } catch {
+    return [];
+  }
+};
+
 export const createHttpSnippet = ({
   operation,
   selectedServer,
@@ -13,11 +30,22 @@ export const createHttpSnippet = ({
     text?: string;
   };
 }) => {
+  const isMultipart =
+    exampleBody.mimeType === "multipart/form-data" ||
+    exampleBody.mimeType === "application/x-www-form-urlencoded";
+
+  const postData = isMultipart
+    ? {
+        mimeType: exampleBody.mimeType,
+        params: toFormDataParams(exampleBody.text),
+      }
+    : exampleBody;
+
   return new HTTPSnippet({
     method: operation.method.toUpperCase(),
     url:
       selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
-    postData: exampleBody,
+    postData,
     headers: [
       ...(exampleBody.text
         ? [{ name: "Content-Type", value: exampleBody.mimeType }]