OpenAPI: support transformAuthInputs

fuma-nama · fuma-nama · commit 297088544f5e · 2025-11-04T21:11:09.000+08:00
diff --git a/.changeset/grumpy-grapes-punch.md b/.changeset/grumpy-grapes-punch.md
@@ -54,4 +54,50 @@ export const APIPage = createAPIPage(openapi, {
     },
   },
 });
-```
+```
+
+2. Remove `disablePlayground` from `createAPIPage()`, use `playground.enabled` instead:
+
+```ts
+// components/api-page.tsx
+import { openapi } from '@/lib/openapi';
+import { createAPIPage } from 'fumadocs-openapi/ui';
+
+export const APIPage = createAPIPage(openapi, {
+  playground: {
+    enabled: false,
+  }
+});
+```
+
+3. Support client config:
+
+```tsx
+// components/api-page.tsx
+import { openapi } from '@/lib/openapi';
+import { createAPIPage } from 'fumadocs-openapi/ui';
+import client from "./api-page.client"
+
+export const APIPage = createAPIPage(openapi, {
+  client,
+});
+```
+
+```tsx
+// components/api-page.client.tsx
+'use client';
+import { defineClientConfig } from 'fumadocs-openapi/ui/client';
+
+export default defineClientConfig({
+  playground: {
+    transformAuthInputs: (inputs) => [
+      ...inputs,
+      {
+        fieldName: 'auth.tests',
+        children: <div>Tests</div>,
+        defaultValue: '',
+      },
+    ],
+  },
+});
+```
diff --git a/packages/openapi/package.json b/packages/openapi/package.json
@@ -22,8 +22,8 @@
       "types": "./dist/ui/index.d.ts"
     },
     "./ui/client": {
-      "import": "./dist/ui/client.js",
-      "types": "./dist/ui/client.d.ts"
+      "import": "./dist/ui/client/index.js",
+      "types": "./dist/ui/client/index.d.ts"
     },
     "./playground": {
       "import": "./dist/playground/index.js",
diff --git a/packages/openapi/src/playground/client.tsx b/packages/openapi/src/playground/client.tsx
@@ -100,7 +100,9 @@ export interface CustomField<TName extends FieldPath<FormValues>, Info> {
   }) => ReactElement;
 }
 
-export interface ClientProps extends HTMLAttributes<HTMLFormElement> {
+export interface ClientProps
+  extends HTMLAttributes<HTMLFormElement>,
+    PlaygroundClientOptions {
   route: string;
   method: string;
   parameters?: ParameterField[];
@@ -115,26 +117,32 @@ export interface ClientProps extends HTMLAttributes<HTMLFormElement> {
   references: Record<string, RequestSchema>;
   proxyUrl?: string;
 
-  /**
-   * Request timeout in seconds (default: 10s)
-   */
-  requestTimeout?: number;
+  // TODO: redesign `fields`
   fields?: {
     parameter?: CustomField<
       `${ParameterField['in']}.${string}`,
       ParameterField
     >;
-    auth?: CustomField<FieldPath<FormValues>, RequestSchema>;
     body?: CustomField<'body', RequestSchema>;
   };
+}
+
+export interface PlaygroundClientOptions {
+  /**
+   * transform fields for auth-specific parameters (e.g. header)
+   */
+  transformAuthInputs?: (fields: AuthField[]) => AuthField[];
+
+  /**
+   * Request timeout in seconds (default: 10s)
+   */
+  requestTimeout?: number;
 
   components?: Partial<{
     ResultDisplay: FC<{ data: FetchResult }>;
   }>;
 }
 
-const AuthPrefix = '__fumadocs_auth';
-
 const OauthDialog = lazy(() =>
   import('./components/oauth-dialog').then((mod) => ({
     default: mod.OauthDialog,
@@ -157,6 +165,7 @@ export default function Client({
   proxyUrl,
   components: { ResultDisplay = DefaultResultDisplay } = {},
   requestTimeout = 10,
+  transformAuthInputs,
   ...rest
 }: ClientProps) {
   const { server } = useServerSelectContext();
@@ -165,7 +174,10 @@ export default function Client({
   const fieldInfoMap = useMemo(() => new Map<string, FieldInfo>(), []);
   const { mediaAdapters } = useApiContext();
   const [securityId, setSecurityId] = useState(0);
-  const { inputs, mapInputs } = useAuthInputs(securities[securityId]);
+  const { inputs, mapInputs } = useAuthInputs(
+    securities[securityId],
+    transformAuthInputs,
+  );
 
   const defaultValues: FormValues = useMemo(
     () => ({
@@ -214,7 +226,7 @@ export default function Client({
 
       if (value) {
         localStorage.setItem(
-          AuthPrefix + item.original.id,
+          getAuthFieldStorageKey(item),
           JSON.stringify(value),
         );
       }
@@ -521,17 +533,20 @@ function BodyInput({ field: _field }: { field: RequestSchema }) {
   );
 }
 
-interface AuthField {
+export interface AuthField {
   fieldName: string;
   defaultValue: unknown;
 
-  original: SecurityEntry;
+  original?: SecurityEntry;
   children: ReactNode;
 
   mapOutput?: (values: unknown) => unknown;
 }
 
-function useAuthInputs(securities?: SecurityEntry[]) {
+function useAuthInputs(
+  securities?: SecurityEntry[],
+  transform?: (fields: AuthField[]) => AuthField[],
+) {
   const inputs = useMemo(() => {
     const result: AuthField[] = [];
     if (!securities) return result;
@@ -672,8 +687,8 @@ function useAuthInputs(securities?: SecurityEntry[]) {
       }
     }
 
-    return result;
-  }, [securities]);
+    return transform ? transform(result) : result;
+  }, [securities, transform]);
 
   const mapInputs = (values: FormValues) => {
     const cloned = structuredClone(values);
@@ -690,9 +705,13 @@ function useAuthInputs(securities?: SecurityEntry[]) {
   return { inputs, mapInputs };
 }
 
+function getAuthFieldStorageKey(field: AuthField) {
+  return '__fumadocs_auth' + (field.original?.id ?? field.fieldName);
+}
+
 function initAuthValues(values: FormValues, inputs: AuthField[]) {
   for (const item of inputs) {
-    const stored = localStorage.getItem(AuthPrefix + item.original.id);
+    const stored = localStorage.getItem(getAuthFieldStorageKey(item));
 
     if (stored) {
       const parsed = JSON.parse(stored);
diff --git a/packages/openapi/src/playground/index.tsx b/packages/openapi/src/playground/index.tsx
@@ -29,8 +29,6 @@ export interface APIPlaygroundProps {
   path: string;
   method: MethodInformation;
   ctx: RenderContext;
-
-  client?: Partial<ClientProps>;
 }
 
 export type { ClientProps, CustomField } from './client';
@@ -40,12 +38,7 @@ export type SecurityEntry = SecuritySchemeObject & {
   id: string;
 };
 
-export async function APIPlayground({
-  path,
-  method,
-  ctx,
-  client,
-}: APIPlaygroundProps) {
+export async function APIPlayground({ path, method, ctx }: APIPlaygroundProps) {
   let currentId = 0;
   const bodyContent = method.requestBody?.content;
   const mediaType = bodyContent ? getPreferredType(bodyContent) : undefined;
@@ -75,7 +68,7 @@ export async function APIPlayground({
         : undefined,
     references: context.references,
     proxyUrl: ctx.proxyUrl,
-    ...client,
+    ...ctx.client?.playground,
   };
 
   return <ClientLazy {...props} />;
diff --git a/packages/openapi/src/ui/api-page.tsx b/packages/openapi/src/ui/api-page.tsx
@@ -11,19 +11,12 @@ import type {
   HighlightOptionsCommon,
   HighlightOptionsThemes,
 } from 'fumadocs-core/highlight';
-import { OpenAPIServer } from '@/server';
+import type { OpenAPIServer } from '@/server';
+import type { APIPageClientOptions } from './client';
 
 type Awaitable<T> = T | Promise<T>;
 
 export interface CreateAPIPageOptions {
-  /**
-   * Disable API Playground
-   *
-   * @defaultValue false
-   * @deprecated Use `playground.enabled` instead
-   */
-  disablePlayground?: boolean;
-
   /**
    * Generate TypeScript definitions from response schema.
    *
@@ -85,6 +78,8 @@ export interface CreateAPIPageOptions {
       ctx: RenderContext;
     }) => ReactNode | Promise<ReactNode>;
   };
+
+  client?: APIPageClientOptions;
 }
 
 export interface ApiPageProps {
@@ -139,7 +134,6 @@ export function createAPIPage(
     const ctx: RenderContext = {
       schema: processed,
       proxyUrl: server.options.proxyUrl,
-      disablePlayground: options.disablePlayground,
       showResponseSchema: options.showResponseSchema,
       renderer: {
         ...createRenders(),
diff --git a/packages/openapi/src/ui/client/index.tsx b/packages/openapi/src/ui/client/index.tsx
@@ -0,0 +1,11 @@
+import type { PlaygroundClientOptions } from '@/playground/client';
+
+export interface APIPageClientOptions {
+  playground?: PlaygroundClientOptions;
+}
+
+export function defineClientConfig(
+  options: APIPageClientOptions,
+): APIPageClientOptions {
+  return options;
+}
diff --git a/packages/openapi/src/ui/operation/index.tsx b/packages/openapi/src/ui/operation/index.tsx
@@ -256,20 +256,20 @@ export function Operation({
     );
   }
 
+  const playgroundEnabled = ctx.playground?.enabled ?? true;
   const info = (
     <ctx.renderer.APIInfo head={headNode} method={method.method} route={path}>
-      {type === 'operation' ? (
-        ctx.disablePlayground ? (
+      {type === 'operation' &&
+        (playgroundEnabled ? (
+          <ctx.renderer.APIPlayground path={path} method={method} ctx={ctx} />
+        ) : (
           <div className="flex flex-row items-center gap-2.5 p-3 rounded-xl border bg-fd-card text-fd-card-foreground not-prose">
             <MethodLabel className="text-xs">{method.method}</MethodLabel>
             <code className="flex-1 overflow-auto text-nowrap text-[13px] text-fd-muted-foreground">
               {path}
             </code>
           </div>
-        ) : (
-          <ctx.renderer.APIPlayground path={path} method={method} ctx={ctx} />
-        )
-      ) : null}
+        ))}
       {authNode}
       {parameterNode}
       {bodyNode}
