OpenAPI: optimize

fuma-nama · fuma-nama · commit 24775bdd2bc6 · 2025-11-04T21:11:09.000+08:00
diff --git a/packages/openapi/package.json b/packages/openapi/package.json
@@ -61,8 +61,8 @@
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.3",
-    "@scalar/json-magic": "^0.7.0",
-    "@scalar/openapi-parser": "0.23.0",
+    "@scalar/json-magic": "^0.6.1",
+    "@scalar/openapi-parser": "0.22.3",
     "ajv": "^8.17.1",
     "class-variance-authority": "^0.7.1",
     "fumadocs-core": "workspace:*",
@@ -80,7 +80,7 @@
     "xml-js": "^1.6.11"
   },
   "devDependencies": {
-    "@scalar/api-client-react": "^1.3.47",
+    "@scalar/api-client-react": "^1.3.46",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "24.10.0",
     "@types/openapi-sampler": "^1.0.3",
diff --git a/packages/openapi/src/playground/client.tsx b/packages/openapi/src/playground/client.tsx
@@ -194,14 +194,14 @@ export default function PlaygroundClient({
   const defaultValues: FormValues = useMemo(() => {
     const requestData = examples.find(
       (example) => example.id === exampleId,
-    )!.data;
+    )?.data;
 
     return {
-      path: requestData.path,
-      query: requestData.query,
-      header: requestData.header,
-      body: requestData.body,
-      cookie: requestData.cookie,
+      path: requestData?.path ?? {},
+      query: requestData?.query ?? {},
+      header: requestData?.header ?? {},
+      body: requestData?.body ?? {},
+      cookie: requestData?.cookie ?? {},
     };
   }, [examples, exampleId]);
 
diff --git a/packages/openapi/src/playground/index.tsx b/packages/openapi/src/playground/index.tsx
@@ -37,6 +37,10 @@ export type SecurityEntry = SecuritySchemeObject & {
 };
 
 export async function APIPlayground({ path, method, ctx }: APIPlaygroundProps) {
+  if (ctx.playground?.render) {
+    return ctx.playground.render({ path, method, ctx });
+  }
+
   let currentId = 0;
   const bodyContent = method.requestBody?.content;
   const mediaType = bodyContent ? getPreferredType(bodyContent) : undefined;
diff --git a/packages/openapi/src/types.ts b/packages/openapi/src/types.ts
@@ -6,6 +6,7 @@ import type { MediaAdapter } from '@/requests/media/adapter';
 import type { OpenAPIOptions } from '@/server';
 import type { CreateAPIPageOptions } from './ui/api-page';
 import type { CodeUsageGenerator } from './ui/operation/api-example';
+import type { ReactNode } from 'react';
 
 export type Document = V3_1.Document;
 export type OperationObject = V3_1.OperationObject;
@@ -38,4 +39,6 @@ export interface RenderContext
   schema: ProcessedDocument;
 
   mediaAdapters: Record<string, MediaAdapter>;
+
+  renderHeading: (depth: number, text: string) => ReactNode;
 }
diff --git a/packages/openapi/src/ui/api-page.tsx b/packages/openapi/src/ui/api-page.tsx
@@ -15,6 +15,7 @@ import type { APIPageClientOptions } from './client';
 import { cn } from 'fumadocs-ui/utils/cn';
 import type { CodeUsageGenerator, ResponseTab } from './operation/api-example';
 import { ApiProvider } from './contexts/api';
+import { Heading } from 'fumadocs-ui/components/heading';
 
 type Awaitable<T> = T | Promise<T>;
 
@@ -160,19 +161,26 @@ export function createAPIPage(
         ? dereferenced.servers
         : [{ url: '/' }];
 
+    const slugger = new Slugger();
     const ctx: RenderContext = {
       schema: processed,
       proxyUrl: server.options.proxyUrl,
-      showResponseSchema: options.showResponseSchema,
-      shikiOptions: options.shikiOptions,
-      generateTypeScriptSchema: options.generateTypeScriptSchema,
-      generateCodeSamples: options.generateCodeSamples,
+      ...options,
       servers,
       mediaAdapters: {
         ...defaultAdapters,
         ...options.mediaAdapters,
       },
-      slugger: new Slugger(),
+      slugger,
+      renderHeading(depth, text) {
+        const id = slugger.slug(text);
+
+        return (
+          <Heading id={id} key={id} as={`h${depth}` as `h1`}>
+            {text}
+          </Heading>
+        );
+      },
     };
 
     return <APIPage {...props} ctx={ctx} />;
diff --git a/packages/openapi/src/ui/components/server/heading.tsx b/packages/openapi/src/ui/components/server/heading.tsx
diff --git a/packages/openapi/src/ui/components/server/markdown.tsx b/packages/openapi/src/ui/components/server/markdown.tsx
@@ -4,7 +4,6 @@ import {
   rehypeCode,
   type RehypeCodeOptions,
   remarkGfm,
-  remarkImage,
 } from 'fumadocs-core/mdx-plugins';
 import defaultMdxComponents from 'fumadocs-ui/mdx';
 import { remark } from 'remark';
@@ -14,7 +13,6 @@ import * as JsxRuntime from 'react/jsx-runtime';
 
 const processor = remark()
   .use(remarkGfm)
-  .use(remarkImage, { useImport: false })
   .use(remarkRehype)
   .use(rehypeCode, {
     langs: [],
diff --git a/packages/openapi/src/ui/contexts/api.tsx b/packages/openapi/src/ui/contexts/api.tsx
@@ -173,7 +173,12 @@ function ServerSelectProvider({
 function getDefaultValues(
   server: NoReference<ServerObject>,
 ): Record<string, string> {
-  return Object.fromEntries(
-    Object.entries(server.variables ?? {}).map(([k, v]) => [k, v.default]),
-  );
+  const out: Record<string, string> = {};
+  if (!server.variables) return out;
+
+  for (const [k, v] of Object.entries(server.variables)) {
+    out[k] = v.default;
+  }
+
+  return out;
 }
diff --git a/packages/openapi/src/ui/contexts/operation.tsx b/packages/openapi/src/ui/contexts/operation.tsx
@@ -18,7 +18,7 @@ export type ExampleUpdateListener = (
 const OperationContext = createContext<{
   route: string;
   examples: APIExampleItem[];
-  example: string;
+  example: string | undefined;
   setExample: (id: string) => void;
   setExampleData: (data: RawRequestData, encoded: RequestData) => void;
 
@@ -38,7 +38,7 @@ export function OperationProvider({
   children: ReactNode;
 }) {
   const [example, setExample] = useState(
-    () => defaultExampleId ?? examples[0].id,
+    () => defaultExampleId ?? examples.at(0)?.id,
   );
   const listeners = useRef<ExampleUpdateListener[]>([]);
 
diff --git a/packages/openapi/src/ui/operation/api-example.tsx b/packages/openapi/src/ui/operation/api-example.tsx
@@ -182,16 +182,18 @@ export async function APIExample({
 
   if (method['x-codeSamples']) {
     for (const sample of method['x-codeSamples']) {
-      generators.push({
-        ...sample,
-        id: 'id' in sample ? (sample.id as string) : sample.lang,
-      });
+      generators.push(
+        'id' in sample && typeof sample.id === 'string'
+          ? (sample as CodeUsageGenerator)
+          : {
+              id: sample.lang,
+              ...sample,
+            },
+      );
     }
   }
 
-  generators = dedupe(
-    generators.filter((generator) => generator.source !== false),
-  );
+  generators = dedupe(generators);
 
   return renderAPIExampleLayout(
     {
@@ -214,7 +216,7 @@ function dedupe(samples: CodeUsageGenerator[]): CodeUsageGenerator[] {
     const item = samples[i];
     if (set.has(item.id)) continue;
     set.add(item.id);
-    out.unshift(item);
+    if (item.source !== false) out.unshift(item);
   }
 
   return out;
diff --git a/packages/openapi/src/ui/operation/client.tsx b/packages/openapi/src/ui/operation/client.tsx
@@ -9,7 +9,7 @@ import {
   createContext,
   type FC,
   type ReactNode,
-  useContext,
+  use,
   useEffect,
   useMemo,
   useState,
@@ -39,7 +39,7 @@ export interface OperationClientOptions {
   APIExampleSelector?: FC<{
     items: APIExampleItem[];
 
-    value: string;
+    value: string | undefined;
     onValueChange: (id: string) => void;
   }>;
 }
@@ -105,7 +105,7 @@ export function SelectTab({
 }: ComponentProps<'div'> & {
   value: string;
 }) {
-  const ctx = useContext(Context);
+  const ctx = use(Context);
   if (value !== ctx?.type) return;
 
   return <div {...props}>{props.children}</div>;
@@ -115,7 +115,7 @@ export function SelectTabTrigger({
   items,
   ...props
 }: ComponentProps<typeof SelectTrigger> & { items: string[] }) {
-  const { type, setType } = useContext(Context)!;
+  const { type, setType } = use(Context)!;
 
   return (
     <Select value={type ?? ''} onValueChange={setType}>
@@ -176,14 +176,14 @@ export function APIExampleUsageTab(sample: CodeUsageGenerator) {
   const { shikiOptions, mediaAdapters } = useApiContext();
   const {
     examples,
-    example: key,
+    example: selectedExampleId,
     route,
     addListener,
     removeListener,
   } = useOperationContext();
   const { server } = useServerSelectContext();
   const [data, setData] = useState(
-    () => examples.find((example) => example.id === key)!.encoded,
+    () => examples.find((example) => example.id === selectedExampleId)?.encoded,
   );
 
   useEffect(() => {
@@ -196,7 +196,7 @@ export function APIExampleUsageTab(sample: CodeUsageGenerator) {
   }, [addListener, removeListener]);
 
   const code = useMemo(() => {
-    if (!sample.source) return;
+    if (!sample.source || !data) return;
     if (typeof sample.source === 'string') return sample.source;
 
     return sample.source(
diff --git a/packages/openapi/src/ui/operation/index.tsx b/packages/openapi/src/ui/operation/index.tsx
@@ -1,9 +1,4 @@
-import {
-  ComponentProps,
-  Fragment,
-  type ReactElement,
-  type ReactNode,
-} from 'react';
+import { type ComponentProps, Fragment, type ReactNode } from 'react';
 import type {
   CallbackObject,
   MethodInformation,
@@ -18,7 +13,6 @@ import {
 } from '@/utils/schema';
 import { idToTitle } from '@/utils/id-to-title';
 import { Markdown } from '../components/server/markdown';
-import { heading } from '../components/server/heading';
 import { Schema } from '../schema';
 import { APIExample, getAPIExamples } from '@/ui/operation/api-example';
 import { MethodLabel } from '@/ui/components/method-label';
@@ -63,7 +57,7 @@ export function Operation({
 
   hasHead?: boolean;
   headingLevel?: number;
-}): ReactElement {
+}) {
   const {
     schema: { dereferenced },
   } = ctx;
@@ -81,7 +75,7 @@ export function Operation({
 
     headNode = (
       <>
-        {heading(headingLevel, title, ctx)}
+        {ctx.renderHeading(headingLevel, title)}
         {method.description ? <Markdown text={method.description} /> : null}
       </>
     );
@@ -94,7 +88,7 @@ export function Operation({
     bodyNode = (
       <SelectTabs defaultValue={contentTypes[0][0]}>
         <div className="flex gap-2 items-end justify-between">
-          {heading(headingLevel, 'Request Body', ctx)}
+          {ctx.renderHeading(headingLevel, 'Request Body')}
           <SelectTabTrigger
             items={contentTypes.map((v) => v[0])}
             className="mb-4"
@@ -129,7 +123,7 @@ export function Operation({
 
     responseNode = (
       <>
-        {heading(headingLevel, 'Response Body', ctx)}
+        {ctx.renderHeading(headingLevel, 'Response Body')}
 
         <Accordions type="multiple">
           {statuses.map((status) => (
@@ -148,7 +142,7 @@ export function Operation({
 
     return (
       <Fragment key={type}>
-        {heading(headingLevel, title, ctx)}
+        {ctx.renderHeading(headingLevel, title)}
         <div className="flex flex-col">
           {params.map((param) => (
             <Schema
@@ -187,7 +181,7 @@ export function Operation({
     authNode = (
       <SelectTabs defaultValue={names[0]}>
         <div className="flex items-end justify-between gap-2">
-          {heading(headingLevel, 'Authorization', ctx)}
+          {ctx.renderHeading(headingLevel, 'Authorization')}
           <SelectTabTrigger items={names} className="mb-4" />
         </div>
         {securities.map((security, i) => (
@@ -217,7 +211,7 @@ export function Operation({
     callbacksNode = (
       <SelectTabs defaultValue={callbacks[0][0]}>
         <div className="flex justify-between gap-2 items-end">
-          {heading(headingLevel, 'Callbacks', ctx)}
+          {ctx.renderHeading(headingLevel, 'Callbacks')}
           <SelectTabTrigger
             items={callbacks.map((v) => v[0])}
             className="mb-4"
diff --git a/packages/openapi/src/utils/get-typescript-schema.ts b/packages/openapi/src/utils/get-typescript-schema.ts
@@ -1,10 +1,11 @@
-import { compile } from '@fumari/json-schema-to-typescript';
 import type { ProcessedDocument } from '@/utils/process-document';
 
 export async function getTypescriptSchema(
   processed: ProcessedDocument,
 ): Promise<string | undefined> {
   try {
+    const { compile } = await import('@fumari/json-schema-to-typescript');
+
     const cloned = structuredClone(processed.bundled);
     return await compile(cloned, 'Response', {
       $refOptions: false,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
