@mehdad67/apitogo 0.1.24

package/src/lib/plugins/openapi/processors/removeParameters.ts

@@ -0,0 +1,103 @@
+import type { ProcessorArg } from "../../../../config/validators/BuildSchema.js";
+import type { OpenAPIDocument } from "../../../oas/parser/index.js";
+import { type RecordAny, traverse } from "./traverse.js";
+
+interface RemoveParametersOptions {
+  // Names of parameters to remove
+  names?: string[];
+  // Specific locations to remove parameters from ('query', 'header', 'path', 'cookie')
+  in?: string[];
+  // Custom filter function
+  shouldRemove?: ({ parameter }: { parameter: RecordAny }) => boolean;
+}
+
+export const removeParameters =
+  ({ names, in: locations, shouldRemove }: RemoveParametersOptions = {}) =>
+  ({ schema }: ProcessorArg) =>
+    traverse(schema, (spec) => {
+      // Helper function to filter parameters
+      const filterParameters = (parameters: RecordAny[]) =>
+        parameters.filter((p) => {
+          if (names?.includes(p.name)) return false;
+          if (locations?.includes(p.in)) return false;
+          if (shouldRemove?.({ parameter: p })) return false;
+          return true;
+        });
+
+      // Handle components.parameters
+      if (spec.components?.parameters) {
+        spec = {
+          ...spec,
+          components: {
+            ...spec.components,
+            parameters: Object.fromEntries(
+              Object.entries(spec.components.parameters).filter(
+                ([_, param]) => {
+                  const p = param as RecordAny;
+                  if (p.$ref) return true; // Skip references
+                  return (
+                    !names?.includes(p.name) &&
+                    !locations?.includes(p.in) &&
+                    !shouldRemove?.({ parameter: p })
+                  );
+                },
+              ),
+            ),
+          },
+        };
+      }
+
+      // Handle paths
+      if (spec.paths) {
+        const updatedPaths: RecordAny = {};
+
+        for (const [path, pathItem] of Object.entries(spec.paths)) {
+          if (typeof pathItem !== "object" || pathItem === null) {
+            updatedPaths[path] = pathItem;
+            continue;
+          }
+
+          let updatedPathItem = { ...pathItem };
+
+          // Handle path-level parameters
+          if (
+            "parameters" in updatedPathItem &&
+            Array.isArray(updatedPathItem.parameters)
+          ) {
+            updatedPathItem.parameters = filterParameters(
+              updatedPathItem.parameters,
+            );
+          }
+
+          // Handle operation-level parameters
+          for (const method of Object.keys(updatedPathItem)) {
+            const pathItemWithMethods = updatedPathItem as Record<
+              string,
+              RecordAny
+            >;
+
+            if (
+              method === "parameters" ||
+              typeof pathItemWithMethods[method] !== "object"
+            ) {
+              continue;
+            }
+
+            const operation = pathItemWithMethods[method];
+            if (Array.isArray(operation.parameters)) {
+              pathItemWithMethods[method] = {
+                ...operation,
+                parameters: filterParameters(operation.parameters),
+              };
+              updatedPathItem = pathItemWithMethods;
+            }
+          }
+
+          updatedPaths[path] = updatedPathItem;
+        }
+
+        spec = { ...spec, paths: updatedPaths };
+      }
+
+      return spec;
+    }) as OpenAPIDocument;

package/src/lib/plugins/openapi/processors/removePaths.ts

@@ -0,0 +1,57 @@
+import type { ProcessorArg } from "../../../../config/validators/BuildSchema.js";
+import type { OpenAPIDocument } from "../../../oas/parser/index.js";
+import { type RecordAny, traverse } from "./traverse.js";
+
+interface RemovePathsOptions {
+  // Path definitions, e.g., { '/path': true, '/path-2': ['get'] }
+  paths?: Record<string, true | string[]>;
+  shouldRemove?: (options: {
+    path: string;
+    method: true | string;
+    operation: RecordAny;
+  }) => boolean;
+}
+
+export const removePaths =
+  ({ paths = {}, shouldRemove }: RemovePathsOptions) =>
+  ({ schema }: ProcessorArg) =>
+    traverse(schema, (spec) => {
+      if (!spec.paths) return spec;
+
+      const updatedPaths: RecordAny = {};
+
+      for (const [path, methods] of Object.entries(spec.paths)) {
+        const operations = spec.paths[path];
+
+        // If the path is explicitly marked for removal in `paths`
+        if (paths[path] === true) continue;
+
+        // If the path should be removed via `shouldRemove`
+        if (shouldRemove?.({ path, method: true, operation: operations }))
+          continue;
+
+        if (typeof methods === "object" && methods !== null) {
+          const filteredPath = Object.fromEntries(
+            Object.entries(methods).filter(([method]) => {
+              const operations = spec.paths[path][method];
+              const isMethodToRemove =
+                Array.isArray(paths[path]) && paths[path].includes(method);
+
+              const isMethodFiltered = shouldRemove?.({
+                path,
+                method,
+                operation: operations,
+              });
+
+              return !isMethodToRemove && !isMethodFiltered;
+            }),
+          );
+
+          updatedPaths[path] = filteredPath;
+        } else {
+          updatedPaths[path] = methods;
+        }
+      }
+
+      return { ...spec, paths: updatedPaths };
+    }) as OpenAPIDocument;

package/src/lib/plugins/openapi/processors/traverse.ts

@@ -0,0 +1 @@
+export { type RecordAny, traverse } from "../../../util/traverse.js";

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

@@ -0,0 +1,39 @@
+import type { SchemaObject } from "../../../oas/parser/index.js";
+import { SelectOnClick } from "../components/SelectOnClick.js";
+
+export const SchemaExampleAndDefault = ({
+  schema,
+}: {
+  schema: SchemaObject;
+}) => {
+  const example = schema.examples?.at(0);
+  const defaultValue = schema.default;
+
+  if (example === undefined && defaultValue === undefined) return null;
+
+  return (
+    <div className="flex flex-col gap-1">
+      {example !== undefined && (
+        <div>
+          <span className="text-muted-foreground">Example: </span>
+          <SelectOnClick className="border rounded-sm px-1 font-mono">
+            {typeof example === "object" || typeof example === "boolean"
+              ? JSON.stringify(example)
+              : example}
+          </SelectOnClick>
+        </div>
+      )}
+      {defaultValue !== undefined && (
+        <div>
+          <span className="text-muted-foreground">Default: </span>
+          <SelectOnClick className="border rounded-sm px-1 font-mono">
+            {typeof defaultValue === "object" ||
+            typeof defaultValue === "boolean"
+              ? JSON.stringify(defaultValue)
+              : defaultValue}
+          </SelectOnClick>
+        </div>
+      )}
+    </div>
+  );
+};

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

@@ -0,0 +1,189 @@
+import {
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemTitle,
+} from "@lukoweb/apitogo/ui/Item.js";
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { MinusIcon, PlusIcon, RefreshCcwDotIcon } from "lucide-react";
+import { useState } from "react";
+import { InlineCode } from "../../../components/InlineCode.js";
+import { Markdown } from "../../../components/Markdown.js";
+import type { SchemaObject } from "../../../oas/parser/index.js";
+import { Button } from "../../../ui/Button.js";
+import { cn } from "../../../util/cn.js";
+import { ConstValue } from "../components/ConstValue.js";
+import { EnumValues } from "../components/EnumValues.js";
+import { ParamInfos } from "../ParamInfos.js";
+import { SchemaExampleAndDefault } from "./SchemaExampleAndDefault.js";
+import { SchemaView } from "./SchemaView.js";
+import {
+  extractCircularRefInfo,
+  isArrayCircularRef,
+  isArrayType,
+  isCircularRef,
+  isComplexType,
+} from "./utils.js";
+
+const RecursiveIndicator = ({ circularProp }: { circularProp?: string }) => (
+  <InlineCode className="inline-flex items-center gap-1.5 text-xs translate-y-0.5">
+    <RefreshCcwDotIcon size={13} />
+    <span>{circularProp ? `${circularProp} (circular)` : "circular"}</span>
+  </InlineCode>
+);
+
+export const SchemaPropertyItem = ({
+  name,
+  schema,
+  group,
+  defaultOpen = false,
+  showCollapseButton = true,
+}: {
+  name: string;
+  schema: SchemaObject;
+  group: "required" | "optional" | "deprecated";
+  defaultOpen?: boolean;
+  showCollapseButton?: boolean;
+}) => {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+
+  const isDeprecated = group === "deprecated";
+
+  if (isCircularRef(schema)) {
+    return (
+      <Item
+        className={cn(
+          isDeprecated && "opacity-50 hover:opacity-100 transition",
+        )}
+      >
+        <ItemContent className="gap-y-2">
+          <div>
+            <ItemTitle className="inline me-2">
+              <code className={cn(isDeprecated && "line-through")}>{name}</code>
+            </ItemTitle>
+            {"\u200B"}
+            <ParamInfos
+              className="inline"
+              schema={schema}
+              extraItems={[
+                group === "required" && (
+                  <span className="text-primary">required</span>
+                ),
+                <RecursiveIndicator key="circular-ref" />,
+              ]}
+            />
+          </div>
+          <SchemaExampleAndDefault schema={schema} />
+        </ItemContent>
+      </Item>
+    );
+  }
+
+  const isCollapsible = Boolean(
+    (schema.allOf ||
+      schema.anyOf ||
+      schema.oneOf ||
+      isComplexType(schema) ||
+      (isArrayType(schema) &&
+        "items" in schema &&
+        isComplexType(schema.items)) ||
+      schema.additionalProperties) &&
+    !isArrayCircularRef(schema),
+  );
+
+  const shouldRenderDescription = Boolean(
+    schema.description ||
+    ("items" in schema && schema.items?.enum) ||
+    schema.const ||
+    schema.enum ||
+    schema.example !== undefined ||
+    schema.default !== undefined,
+  );
+
+  return (
+    <Item
+      className={cn(isDeprecated && "opacity-50 hover:opacity-100 transition")}
+    >
+      <ItemContent className="gap-y-2">
+        <div>
+          <ItemTitle className="inline me-2">
+            {isCollapsible ? (
+              <button
+                onClick={() => setIsOpen(!isOpen)}
+                type="button"
+                className="hover:underline"
+              >
+                <code className={cn(isDeprecated && "line-through")}>
+                  {name}
+                </code>
+              </button>
+            ) : (
+              <code className={cn(isDeprecated && "line-through")}>{name}</code>
+            )}
+          </ItemTitle>
+          {"\u200B"}
+          <ParamInfos
+            className="inline"
+            schema={schema}
+            extraItems={[
+              group === "required" && (
+                <span className="text-primary">required</span>
+              ),
+              isArrayCircularRef(schema) && (
+                <RecursiveIndicator
+                  circularProp={extractCircularRefInfo(schema.items)}
+                />
+              ),
+            ]}
+          />
+        </div>
+        {shouldRenderDescription && (
+          <div className="flex flex-col gap-1.5">
+            {schema.description && (
+              <Markdown className="prose-sm" content={schema.description} />
+            )}
+            {"items" in schema && schema.items?.enum && (
+              <EnumValues values={schema.items.enum} />
+            )}
+            {schema.const && <ConstValue schema={schema} hideDescription />}
+            {schema.enum && <EnumValues values={schema.enum} />}
+            <SchemaExampleAndDefault schema={schema} />
+          </div>
+        )}
+      </ItemContent>
+
+      {isCollapsible && showCollapseButton && (
+        <ItemActions className="self-start">
+          <Button
+            variant="ghost"
+            size="icon"
+            className="rounded-full"
+            onClick={() => setIsOpen(!isOpen)}
+            aria-label="Toggle properties"
+          >
+            {isOpen ? <MinusIcon size={16} /> : <PlusIcon size={16} />}
+          </Button>
+        </ItemActions>
+      )}
+
+      {isCollapsible && (
+        <Collapsible.Root
+          defaultOpen={defaultOpen}
+          open={isOpen}
+          onOpenChange={setIsOpen}
+          className={cn("w-full", !isOpen && "contents")}
+        >
+          <Collapsible.Content asChild>
+            <ItemContent>
+              {schema.anyOf || schema.oneOf || schema.type === "object" ? (
+                <SchemaView schema={schema} />
+              ) : isArrayType(schema) && "items" in schema ? (
+                <SchemaView schema={schema.items} />
+              ) : null}
+            </ItemContent>
+          </Collapsible.Content>
+        </Collapsible.Root>
+      )}
+    </Item>
+  );
+};

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

@@ -0,0 +1,299 @@
+import {
+  Frame,
+  FrameDescription,
+  FrameFooter,
+  FrameHeader,
+  FramePanel,
+} from "@lukoweb/apitogo/ui/Frame.js";
+import { ItemGroup, ItemSeparator } from "@lukoweb/apitogo/ui/Item.js";
+import { EyeIcon, EyeOffIcon, InfoIcon } from "lucide-react";
+import { Fragment, useId, useLayoutEffect, useRef, useState } from "react";
+import { Markdown } from "../../../components/Markdown.js";
+import type { SchemaObject } from "../../../oas/parser/index.js";
+import { ConstValue } from "../components/ConstValue.js";
+import { EnumValues } from "../components/EnumValues.js";
+import { ParamInfos } from "../ParamInfos.js";
+import { SchemaExampleAndDefault } from "./SchemaExampleAndDefault.js";
+import { SchemaPropertyItem } from "./SchemaPropertyItem.js";
+import { UnionView } from "./UnionView.js";
+import { isArrayType, isBasicType } from "./utils.js";
+
+const renderMarkdown = (content?: string) =>
+  content && (
+    <Markdown
+      className="text-sm leading-normal line-clamp-4"
+      content={content}
+    />
+  );
+
+const renderBasicSchema = (
+  schema: SchemaObject,
+  cardHeader?: React.ReactNode,
+  embedded?: boolean,
+) => {
+  const content = (
+    <>
+      <span className="text-sm text-muted-foreground">
+        <ParamInfos schema={schema} />
+      </span>
+      {schema.enum && <EnumValues values={schema.enum} />}
+      {renderMarkdown(schema.description)}
+      <SchemaExampleAndDefault schema={schema} />
+    </>
+  );
+
+  if (embedded) {
+    return <div className="space-y-2 p-4">{content}</div>;
+  }
+
+  return (
+    <Frame>
+      {cardHeader}
+      <FramePanel className="space-y-2">{content}</FramePanel>
+    </Frame>
+  );
+};
+
+const PropertyGroup = ({
+  properties,
+  group,
+  defaultOpen,
+}: {
+  properties: [string, SchemaObject][];
+  group: "required" | "optional" | "deprecated";
+  defaultOpen: boolean;
+}) => (
+  <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>
+);
+
+const DeprecatedToggle = ({
+  count,
+  showDeprecated,
+  onToggle,
+  controlsId,
+}: {
+  count: number;
+  showDeprecated: boolean;
+  onToggle: () => void;
+  controlsId: string;
+}) => (
+  <button
+    type="button"
+    onClick={onToggle}
+    aria-expanded={showDeprecated}
+    aria-controls={controlsId}
+    className="text-xs text-muted-foreground flex items-center gap-1.5 hover:text-foreground transition-colors cursor-pointer"
+  >
+    {showDeprecated ? <EyeOffIcon size={14} /> : <EyeIcon size={14} />}
+    {showDeprecated
+      ? "Hide deprecated fields"
+      : `Show ${count} deprecated field${count !== 1 ? "s" : ""}`}
+  </button>
+);
+
+const ObjectSchemaView = ({
+  schema,
+  defaultOpen,
+  cardHeader,
+  embedded,
+}: {
+  schema: SchemaObject;
+  defaultOpen: boolean;
+  cardHeader?: React.ReactNode;
+  embedded?: boolean;
+}) => {
+  const [showDeprecated, setShowDeprecated] = useState(false);
+  const deprecatedRef = useRef<HTMLDivElement>(null);
+  const deprecatedId = useId();
+
+  // Upgrade hidden → hidden="until-found" so browser Cmd+F can find text inside.
+  // Uses useLayoutEffect to set the attribute before paint, avoiding flash.
+  // Managed imperatively because React types don't support "until-found" value.
+  useLayoutEffect(() => {
+    const el = deprecatedRef.current;
+    if (!el) return;
+
+    if (!showDeprecated) {
+      el.setAttribute("hidden", "until-found");
+    } else {
+      el.removeAttribute("hidden");
+    }
+
+    const handler = () => setShowDeprecated(true);
+    el.addEventListener("beforematch", handler);
+    return () => el.removeEventListener("beforematch", handler);
+  }, [showDeprecated]);
+
+  const groupedProperties = Object.groupBy(
+    Object.entries(schema.properties ?? {}),
+    ([propertyName, property]) => {
+      return property.deprecated
+        ? "deprecated"
+        : schema.required?.includes(propertyName)
+          ? "required"
+          : "optional";
+    },
+  );
+
+  const nonDeprecatedGroupNames = ["required", "optional"] as const;
+  const nonDeprecatedGroups = nonDeprecatedGroupNames.flatMap((group) => {
+    const properties = groupedProperties[group];
+    return properties ? { group, properties } : [];
+  });
+
+  const deprecatedProperties = groupedProperties["deprecated"];
+
+  const additionalObjectProperties = typeof schema.additionalProperties ===
+    "object" && <SchemaView schema={schema.additionalProperties} embedded />;
+
+  const itemsList = nonDeprecatedGroups.map(({ group, properties }, index) => (
+    <Fragment key={group}>
+      {index > 0 && <ItemSeparator />}
+      <PropertyGroup
+        properties={properties}
+        group={group}
+        defaultOpen={defaultOpen}
+      />
+    </Fragment>
+  ));
+
+  const deprecatedList = deprecatedProperties && (
+    <>
+      {nonDeprecatedGroups.length > 0 && <ItemSeparator />}
+      <PropertyGroup
+        properties={deprecatedProperties}
+        group="deprecated"
+        defaultOpen={defaultOpen}
+      />
+    </>
+  );
+
+  if (embedded) {
+    return (
+      <>
+        {itemsList}
+        {deprecatedList}
+      </>
+    );
+  }
+
+  return (
+    <Frame>
+      {cardHeader}
+      {schema.description && (
+        <FrameHeader>
+          <FrameDescription>{schema.description}</FrameDescription>
+        </FrameHeader>
+      )}
+      {(nonDeprecatedGroups.length > 0 ||
+        deprecatedProperties ||
+        additionalObjectProperties) && (
+        <FramePanel className="p-0!">
+          {itemsList}
+          {deprecatedProperties && (
+            <div ref={deprecatedRef} id={deprecatedId} hidden={!showDeprecated}>
+              {deprecatedList}
+            </div>
+          )}
+          {additionalObjectProperties}
+        </FramePanel>
+      )}
+      {(schema.additionalProperties === true || deprecatedProperties) && (
+        <FrameFooter className="flex-row items-center justify-between">
+          {schema.additionalProperties === true ? (
+            <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>
+          ) : (
+            <span />
+          )}
+          {deprecatedProperties && (
+            <DeprecatedToggle
+              count={deprecatedProperties.length}
+              showDeprecated={showDeprecated}
+              onToggle={() => setShowDeprecated(!showDeprecated)}
+              controlsId={deprecatedId}
+            />
+          )}
+        </FrameFooter>
+      )}
+    </Frame>
+  );
+};
+
+export const SchemaView = ({
+  schema,
+  defaultOpen = false,
+  cardHeader,
+  embedded,
+}: {
+  schema?: SchemaObject | null;
+  defaultOpen?: boolean;
+  cardHeader?: React.ReactNode;
+  embedded?: boolean;
+}) => {
+  if (!schema || Object.keys(schema).length === 0) {
+    return (
+      <Frame>
+        {cardHeader}
+        <FramePanel>
+          <div className="text-sm text-muted-foreground italic">
+            No data returned
+          </div>
+        </FramePanel>
+      </Frame>
+    );
+  }
+
+  if (schema.const) {
+    return <ConstValue schema={schema} />;
+  }
+
+  if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) {
+    return <UnionView schema={schema} cardHeader={cardHeader} />;
+  }
+
+  if (isBasicType(schema.type)) {
+    return renderBasicSchema(schema, cardHeader, embedded);
+  }
+
+  if (isArrayType(schema) && typeof schema.items === "object") {
+    const wrappedSchema: SchemaObject = {
+      type: "object",
+      properties: { "": schema },
+    };
+
+    return (
+      <SchemaView schema={wrappedSchema} cardHeader={cardHeader} defaultOpen />
+    );
+  }
+
+  if (schema.type === "object") {
+    return (
+      <ObjectSchemaView
+        schema={schema}
+        defaultOpen={defaultOpen}
+        cardHeader={cardHeader}
+        embedded={embedded}
+      />
+    );
+  }
+};