zudoku 0.0.0-ec30b50 → 0.0.0-edd80c1

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

@@ -1,171 +1,132 @@
+import { InfoIcon } from "lucide-react";
 import { Markdown, ProseClasses } from "../../../components/Markdown.js";
 import type { SchemaObject } from "../../../oas/parser/index.js";
-import { Card, CardContent, CardHeader, CardTitle } from "../../../ui/Card.js";
+import { Card } from "../../../ui/Card.js";
 import { cn } from "../../../util/cn.js";
 import { groupBy } from "../../../util/groupBy.js";
+import { ConstValue } from "../components/ConstValue.js";
+import { EnumValues } from "../components/EnumValues.js";
+import { ParamInfos } from "../ParamInfos.js";
+import { SchemaExampleAndDefault } from "./SchemaExampleAndDefault.js";
 import {
   SchemaLogicalGroup,
   SchemaPropertyItem,
 } from "./SchemaPropertyItem.js";
-import { hasLogicalGroupings } from "./utils.js";
+import { hasLogicalGroupings, isBasicType } from "./utils.js";
+
+const renderMarkdown = (content?: string) =>
+  content && (
+    <Markdown
+      className={cn(ProseClasses, "text-sm leading-normal line-clamp-4")}
+      content={content}
+    />
+  );
+
+const renderBasicSchema = (schema: SchemaObject) => (
+  <Card className="p-4 space-y-2">
+    <span className="text-sm text-muted-foreground">
+      <ParamInfos schema={schema} />
+    </span>
+    {schema.enum && <EnumValues values={schema.enum} />}
+    {renderMarkdown(schema.description)}
+    <SchemaExampleAndDefault schema={schema} />
+  </Card>
+);
 
 export const SchemaView = ({
   schema,
-  level = 0,
   defaultOpen = false,
+  cardHeader,
 }: {
   schema?: SchemaObject | null;
-  level?: number;
   defaultOpen?: boolean;
+  cardHeader?: React.ReactNode;
 }) => {
   if (!schema || Object.keys(schema).length === 0) {
     return (
-      <Card className="p-4">
-        <span className="text-sm text-muted-foreground italic">
-          No response specified
-        </span>
+      <Card className="overflow-hidden">
+        {cardHeader}
+        <div className="text-sm text-muted-foreground italic p-4">
+          No schema specified
+        </div>
       </Card>
     );
   }
 
-  const renderSchema = (schema: SchemaObject, level: number) => {
-    if (hasLogicalGroupings(schema)) {
-      return <SchemaLogicalGroup schema={schema} level={level} />;
-    }
-
-    // Sometimes items is not defined
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (schema.type === "array" && schema.items) {
-      const itemsSchema = schema.items as SchemaObject;
-
-      if (
-        typeof itemsSchema.type === "string" &&
-        ["string", "number", "boolean", "integer"].includes(itemsSchema.type)
-      ) {
-        return (
-          <Card className="p-4">
-            <span className="text-sm text-muted-foreground">
-              {itemsSchema.type}[]
-            </span>
-            {schema.description && (
-              <Markdown
-                className={cn(
-                  ProseClasses,
-                  "text-sm leading-normal line-clamp-4",
-                )}
-                content={schema.description}
-              />
-            )}
-          </Card>
-        );
-      } else if (itemsSchema.type === "object") {
-        return (
-          <Card className="flex flex-col gap-2 bg-border/30 p-4">
-            <span className="text-sm text-muted-foreground">object[]</span>
-            {renderSchema(itemsSchema, level + 1)}
-          </Card>
-        );
-      } else {
-        return renderSchema(itemsSchema, level + 1);
-      }
-    }
+  if (schema.const) {
+    return <ConstValue schema={schema} />;
+  }
 
-    if (
-      schema.type === "object" &&
-      (!schema.properties || Object.keys(schema.properties).length === 0)
-    ) {
-      return (
-        <Card className="p-4 flex gap-2 items-center">
-          {"name" in schema && <>{schema.name as string}</>}
-          <span className="text-sm text-muted-foreground">object</span>
-          {schema.description && (
-            <Markdown
-              className={cn(
-                ProseClasses,
-                "text-sm leading-normal line-clamp-4",
-              )}
-              content={schema.description}
-            />
-          )}
-        </Card>
-      );
-    }
+  if (hasLogicalGroupings(schema)) {
+    return <SchemaLogicalGroup schema={schema} />;
+  }
 
-    if (schema.properties) {
-      const groupedProperties = groupBy(
-        Object.entries(schema.properties),
-        ([propertyName, property]) => {
-          return property.deprecated
-            ? "deprecated"
-            : schema.required?.includes(propertyName)
-              ? "required"
-              : "optional";
-        },
-      );
+  if (isBasicType(schema.type)) {
+    return renderBasicSchema(schema);
+  }
 
-      const groupNames = ["required", "optional", "deprecated"] as const;
+  if (schema.type === "array" && typeof schema.items === "object") {
+    return <SchemaView schema={schema.items} />;
+  }
 
-      return (
-        <Card className="divide-y overflow-hidden">
-          {groupNames.map(
-            (group) =>
-              groupedProperties[group] && (
-                <ul key={group} className="divide-y">
-                  {groupedProperties[group].map(([name, schema]) => (
-                    <SchemaPropertyItem
-                      key={name}
-                      name={name}
-                      schema={schema}
-                      group={group}
-                      level={level}
-                      defaultOpen={defaultOpen}
-                    />
-                  ))}
-                </ul>
-              ),
-          )}
-        </Card>
-      );
-    }
+  if (schema.type === "object") {
+    const groupedProperties = groupBy(
+      Object.entries(schema.properties ?? {}),
+      ([propertyName, property]) => {
+        return property.deprecated
+          ? "deprecated"
+          : schema.required?.includes(propertyName)
+            ? "required"
+            : "optional";
+      },
+    );
+    const groupNames = ["required", "optional", "deprecated"] as const;
 
-    if (
-      typeof schema.type === "string" &&
-      ["string", "number", "boolean", "integer", "null"].includes(schema.type)
-    ) {
-      return (
-        <Card className="p-4">
-          <span className="text-sm text-muted-foreground">{schema.type}</span>
-          {schema.description && (
-            <Markdown
-              className={cn(
-                ProseClasses,
-                "text-sm leading-normal line-clamp-4",
-              )}
-              content={schema.description}
-            />
+    const additionalProperties =
+      typeof schema.additionalProperties === "object" ? (
+        <SchemaView schema={schema.additionalProperties} />
+      ) : schema.additionalProperties === true ? (
+        <div
+          className={cn(
+            ProseClasses,
+            "text-sm p-4 bg-border/20 hover:bg-border/30 flex items-center gap-1",
           )}
-        </Card>
-      );
-    }
-
-    if (schema.additionalProperties) {
-      return (
-        <Card className="my-2">
-          <CardHeader>
-            <CardTitle>Additional Properties:</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {renderSchema(
-              schema.additionalProperties as SchemaObject,
-              level + 1,
-            )}
-          </CardContent>
-        </Card>
-      );
-    }
+        >
+          <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;
 
-    return null;
-  };
+    return (
+      <Card className="divide-y overflow-hidden">
+        {cardHeader}
+        {groupNames.map(
+          (group) =>
+            groupedProperties[group] && (
+              <ul key={group} className="divide-y">
+                {groupedProperties[group].map(([name, schema]) => (
+                  <SchemaPropertyItem
+                    key={name}
+                    name={name}
+                    schema={schema}
+                    group={group}
+                    defaultOpen={defaultOpen}
+                  />
+                ))}
+              </ul>
+            ),
+        )}
+        {additionalProperties}
+      </Card>
+    );
+  }
 
-  return renderSchema(schema, level);
+  return null;
 };

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

@@ -1,11 +1,24 @@
 import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
 import type { SchemaObject } from "../../../oas/parser/index.js";
 
-export const isComplexType = (value: SchemaObject) =>
-  value.type === "object" ||
-  (value.type === "array" &&
-    typeof value.items === "object" &&
-    (!value.items.type || value.items.type === "object"));
+export const isBasicType = (
+  type: unknown,
+): type is "string" | "number" | "boolean" | "integer" | "null" =>
+  typeof type === "string" &&
+  ["string", "number", "boolean", "integer", "null"].includes(type);
+
+export const isArrayType = (value: SchemaObject) =>
+  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"));
+
+export const isComplexType = (value?: SchemaObject) =>
+  value &&
+  ((value.type === "object" &&
+    Object.keys(value.properties ?? {}).length > 0) ||
+    (value.type === "array" &&
+      typeof value.items === "object" &&
+      (!value.items.type || value.items.type === "object")));
 
 export const hasLogicalGroupings = (value: SchemaObject) =>
   Boolean(value.oneOf ?? value.allOf ?? value.anyOf);
@@ -19,4 +32,14 @@ export const LogicalSchemaTypeMap = {
 export type LogicalGroupType = "AND" | "OR" | "ONE";
 
 export const isCircularRef = (schema: unknown): schema is string =>
-  schema === CIRCULAR_REF;
+  typeof schema === "string" && schema.startsWith(CIRCULAR_REF);
+
+export const isArrayCircularRef = (
+  schema: SchemaObject,
+): schema is SchemaObject & { items: SchemaObject } =>
+  isArrayType(schema) && "items" in schema && isCircularRef(schema.items);
+
+export const extractCircularRefInfo = (
+  ref?: string | SchemaObject,
+): string | undefined =>
+  typeof ref === "string" ? ref.split(":")[1] : undefined;

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

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+interface SelectedServerState {
+  selectedServer?: string;
+  setSelectedServer: (newServer: string) => void;
+}
+
+export const useSelectedServerStore = create<SelectedServerState>()(
+  persist(
+    (set) => ({
+      selectedServer: undefined,
+      setSelectedServer: (newServer: string) =>
+        set({ selectedServer: newServer }),
+    }),
+    { name: "zudoku-selected-server" },
+  ),
+);
+
+/**
+ * Simple wrapper for `useSelectedServerStore` to fall back to first of the provided servers
+ */
+export const useSelectedServer = (servers: Array<{ url: string }>) => {
+  const { selectedServer, setSelectedServer } = useSelectedServerStore();
+
+  const finalSelectedServer = useMemo(
+    () =>
+      selectedServer && servers.some((s) => s.url === selectedServer)
+        ? selectedServer
+        : (servers.at(0)?.url ?? ""),
+    [selectedServer, servers],
+  );
+
+  return { selectedServer: finalSelectedServer, setSelectedServer };
+};

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

@@ -0,0 +1,107 @@
+import { HTTPSnippet } from "@zudoku/httpsnippet";
+import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+
+export const createHttpSnippet = ({
+  operation,
+  selectedServer,
+  exampleBody,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedServer: string;
+  exampleBody: {
+    mimeType: string;
+    text?: string;
+  };
+}) => {
+  return new HTTPSnippet({
+    method: operation.method.toUpperCase(),
+    url:
+      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    postData: exampleBody,
+    headers: [
+      ...(exampleBody.text
+        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
+        : []),
+      ...(operation.parameters
+        ?.filter((p) => p.in === "header" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? []),
+    ],
+    queryString:
+      operation.parameters
+        ?.filter((p) => p.in === "query" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? [],
+    httpVersion: "",
+    cookies: [],
+    headersSize: 0,
+    bodySize: 0,
+  });
+};
+
+export const getConverted = (snippet: HTTPSnippet, option: string) => {
+  let converted;
+  switch (option) {
+    case "shell":
+      converted = snippet.convert("shell", "curl");
+      break;
+    case "js":
+      converted = snippet.convert("javascript", "fetch");
+      break;
+    case "python":
+      converted = snippet.convert("python", "requests");
+      break;
+    case "java":
+      converted = snippet.convert("java", "okhttp");
+      break;
+    case "go":
+      converted = snippet.convert("go", "native");
+      break;
+    case "csharp":
+      converted = snippet.convert("csharp", "httpclient");
+      break;
+    case "kotlin":
+      converted = snippet.convert("kotlin", "okhttp");
+      break;
+    case "objc":
+      converted = snippet.convert("objc", "nsurlsession");
+      break;
+    case "php":
+      converted = snippet.convert("php", "http2");
+      break;
+    case "ruby":
+      converted = snippet.convert("ruby");
+      break;
+    case "swift":
+      converted = snippet.convert("swift");
+      break;
+    default:
+      converted = snippet.convert("shell");
+      break;
+  }
+
+  return converted ? converted[0] : "";
+};

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

@@ -0,0 +1,37 @@
+import type { SidebarItem } from "../../../../config/validators/SidebarSchema.js";
+import type { OperationResult } from "../index.js";
+import { MethodColorMap } from "./methodColorMap.js";
+
+export const createSidebarCategory = ({
+  label,
+  path,
+  operations,
+  collapsible,
+  collapsed,
+}: {
+  label: string;
+  path: string;
+  operations: OperationResult[];
+  collapsible?: boolean;
+  collapsed?: boolean;
+}): SidebarItem => ({
+  type: "category",
+  label,
+  link: {
+    type: "doc" as const,
+    id: path,
+    label,
+  },
+  collapsible,
+  collapsed,
+  items: operations.map((operation) => ({
+    type: "link" as const,
+    label: operation.summary ?? operation.path,
+    href: `${path}#${operation.slug}`,
+    badge: {
+      label: operation.method,
+      color: MethodColorMap[operation.method.toLowerCase()]!,
+      invert: true,
+    },
+  })),
+});

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

@@ -1,10 +1,15 @@
 import { type SchemaObject } from "../../../oas/graphql/index.js";
+import { isCircularRef } from "../schema/utils.js";
 
 export const generateSchemaExample = (
-  schema: SchemaObject,
+  schema?: SchemaObject,
   name?: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): any => {
+  if (!schema || isCircularRef(schema)) {
+    return null;
+  }
+
   // Check for schema-level example first
   if (schema.example !== undefined) {
     return schema.example;
@@ -24,6 +29,11 @@ export const generateSchemaExample = (
     }
   }
 
+  // No example needed for const values
+  if (schema.const !== undefined) {
+    return schema.const;
+  }
+
   // For object schemas with properties
   if (schema.type === "object" && schema.properties) {
     const example: Record<string, any> = {};
@@ -50,10 +60,50 @@ export const generateSchemaExample = (
     return [];
   }
 
+  if (schema.format !== undefined) {
+    // Partial implementation of JSON Schema format examples
+    // https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3
+    switch (schema.format) {
+      case "date-time":
+        return "2024-08-25T15:00:00Z";
+      case "date":
+        return "2024-08-25";
+      case "time":
+        return "15:00:00";
+      case "email":
+        return "test@example.com";
+      case "uri":
+        return "https://www.example.com/path/to/resource";
+      case "uri-reference":
+        return "/path/to/resource";
+      case "uuid":
+        return "00000000-0000-0000-0000-000000000000";
+    }
+  }
+
   if (schema.enum) {
     return schema.enum[0];
   }
 
+  if (schema.oneOf) {
+    const randomIndex = Math.floor(Math.random() * schema.oneOf.length);
+    return generateSchemaExample(schema.oneOf[randomIndex] as SchemaObject);
+  }
+
+  if (schema.anyOf) {
+    // Should likely be expanded to return a partial set of values, but it would require
+    // detection if being used within an array or a string type.
+    const randomIndex = Math.floor(Math.random() * schema.anyOf.length);
+    return generateSchemaExample(schema.anyOf[randomIndex] as SchemaObject);
+  }
+
+  if (schema.allOf) {
+    // https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/#allof
+    return schema.allOf.reduce((acc, allOfSchema) => {
+      return { ...acc, ...generateSchemaExample(allOfSchema as SchemaObject) };
+    }, {});
+  }
+
   switch (schema.type) {
     case "string":
       return name || "string";