OpenAPI: Support Parameter Serialization

Author: fuma-nama

.changeset/spicy-mails-brake.md

@@ -0,0 +1,7 @@
+---
+'fumadocs-openapi': minor
+---
+
+**Support Parameter Serialization**
+
+Maybe need to update your code if you've added custom media adapters.

apps/docs/content/docs/ui/(integrations)/openapi/media-adapters.mdx

@@ -5,16 +5,14 @@ description: Support other media types
 
 ## Overview
 
-A media adapter in Fumadocs handle:
+A media adapter in Fumadocs supports:
 
-- Encode: convert form data into `fetch()` body with corresponding media type.
-- Example: generate code example based on different programming language/tool.
+- Converting value into `fetch()` body compatible with corresponding media type.
+- Generate code example based on different programming language/tool.
 
-Put your media adapters in a separate file with `use client` directive.
-
-```ts title="lib/media-adapters.ts" twoslash
-'use client';
+Put your media adapters in a separate file.
 
+```ts tab="lib/media-adapters.ts" twoslash
 import type { MediaAdapter } from 'fumadocs-openapi';
 
 export const myAdapter: MediaAdapter = {
@@ -40,15 +38,28 @@ export const myAdapter: MediaAdapter = {
 };
 ```
 
+```ts tab="lib/media-adapters.client.ts"
+'use client';
+
+// forward them so that Fumadocs can also use your media adapter in a client component
+export { myAdapter } from './media-adapters';
+```
+
+Pass the adapter.
+
 ```ts title="lib/source.ts"
 import { createOpenAPI } from 'fumadocs-openapi/server';
-import { myAdapter } from './media-adapters';
+import * as Adapters from './media-adapters';
+import * as ClientAdapters from './media-adapters.client';
 
 export const openapi = createOpenAPI({
   proxyUrl: '/api/proxy',
   mediaAdapters: {
-    // [!code ++] override the default adapter of `application/json`
-    'application/json': myAdapter,
+    // [!code ++:4] override the default adapter of `application/json`
+    'application/json': {
+      ...Adapters.myAdapter,
+      client: ClientAdapters.myAdapter,
+    },
   },
 });
 ```

packages/openapi/src/media/adapter.ts

@@ -1,6 +1,6 @@
-'use client';
 import { escapeString, inputToString } from '@/utils/input-to-string';
-import type { RequestData } from '@/requests/_shared';
+// @ts-expect-error -- untyped
+import { js2xml } from 'xml-js/lib/js2xml';
 
 interface BaseContext {
   /**
@@ -38,22 +38,32 @@ export type MediaContext =
 
 export interface MediaAdapter {
   /**
-   * encode request data into body for `fetch()`.
+   * the same adapter that's passed from a client component.
+   *
+   * It is needed for client-side serialization of values.
+   */
+  client?: MediaAdapter;
+
+  /**
+   * encode data into specified media type for `fetch()`.
    *
    * Return the encoded form of `data.body` property.
    */
-  encode: (data: RequestData) => BodyInit | Promise<BodyInit>;
+  encode: (data: { body: unknown }) => BodyInit;
 
   /**
-   * generate code for usage examples in a given programming language.
+   * generate code example for creating the body in a given programming language.
    *
    * @param data - request data.
    * @param lang - name of programming language.
    * @param ctx - context passed from the generator of programming language.
    *
    * @returns code that inits a `body` variable, or undefined if not supported (skip example for that language).
    */
-  generateExample: (data: RequestData, ctx: MediaContext) => string | undefined;
+  generateExample: (
+    data: { body: unknown },
+    ctx: MediaContext,
+  ) => string | undefined;
 }
 
 export const defaultAdapters = {
@@ -66,10 +76,7 @@ export const defaultAdapters = {
     },
   },
   'application/xml': {
-    async encode(data) {
-      // @ts-expect-error -- untyped
-      const { js2xml } = await import('xml-js/lib/js2xml');
-
+    encode(data) {
       return js2xml(data.body as Record<string, unknown>, {
         compact: true,
         spaces: 2,
@@ -84,6 +91,7 @@ export const defaultAdapters = {
       if (Array.isArray(data.body)) {
         return data.body.map((v) => JSON.stringify(v)).join('\n');
       }
+
       return JSON.stringify(data.body);
     },
     generateExample(data, ctx) {

packages/openapi/src/playground/client.tsx

@@ -46,7 +46,7 @@ import {
   CollapsibleTrigger,
 } from 'fumadocs-ui/components/ui/collapsible';
 import { ChevronDown, LoaderCircle } from 'lucide-react';
-import type { RequestData } from '@/requests/_shared';
+import { encodeRequestData, type RequestData } from '@/requests/_shared';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
 import { cn } from 'fumadocs-ui/utils/cn';
 import {
@@ -68,13 +68,16 @@ import {
   SelectValue,
 } from '@/ui/components/select';
 import { labelVariants } from '@/ui/components/input';
+import type { ParsedSchema } from '@/utils/schema';
 
 interface FormValues {
-  path: Record<string, string>;
-  query: Record<string, string>;
-  header: Record<string, string>;
-  cookie: Record<string, string>;
+  path: Record<string, unknown>;
+  query: Record<string, unknown>;
+  header: Record<string, unknown>;
+  cookie: Record<string, unknown>;
   body: unknown;
+
+  _encoded?: RequestData;
 }
 
 export interface CustomField<TName extends FieldPath<FormValues>, Info> {
@@ -120,22 +123,6 @@ export interface ClientProps extends HTMLAttributes<HTMLFormElement> {
 
 const AuthPrefix = '__fumadocs_auth';
 
-function toRequestData(
-  method: string,
-  mediaType: string | undefined,
-  value: FormValues,
-): RequestData {
-  return {
-    path: value.path,
-    method,
-    header: value.header,
-    body: value.body,
-    bodyMediaType: mediaType,
-    cookie: value.cookie,
-    query: value.query,
-  };
-}
-
 const ServerSelect = lazy(() => import('@/ui/server-select'));
 const OauthDialog = lazy(() =>
   import('./auth/oauth-dialog').then((mod) => ({
@@ -152,7 +139,7 @@ export default function Client({
   route,
   method = 'GET',
   securities,
-  parameters,
+  parameters = [],
   body,
   fields,
   references,
@@ -187,19 +174,24 @@ export default function Client({
     const fetcher = await import('./fetcher').then((mod) =>
       mod.createBrowserFetcher(mediaAdapters),
     );
-    const data = toRequestData(method, body?.mediaType, input);
+
+    input._encoded ??= encodeRequestData(
+      { ...mapInputs(input), method, bodyMediaType: body?.mediaType },
+      mediaAdapters,
+      parameters,
+    );
 
     return fetcher.fetch(
       joinURL(
         withBase(
           server ? resolveServerUrl(server.url, server.variables) : '/',
           window.location.origin,
         ),
-        resolveRequestData(route, data),
+        resolveRequestData(route, input._encoded),
       ),
       {
         proxyUrl,
-        ...data,
+        ...input._encoded,
       },
     );
   });
@@ -254,7 +246,13 @@ export default function Client({
       }
     }
 
-    updater.setData(toRequestData(method, body?.mediaType, mapInputs(values)));
+    const data = {
+      ...mapInputs(values),
+      method,
+      bodyMediaType: body?.mediaType,
+    };
+    values._encoded ??= encodeRequestData(data, mediaAdapters, parameters);
+    updater.setData(data, values._encoded);
   });
 
   useEffect(() => {
@@ -265,6 +263,9 @@ export default function Client({
         values: true,
       },
       callback({ values }) {
+        // remove cached encoded request data
+        delete values._encoded;
+
         if (timer) window.clearTimeout(timer);
         timer = window.setTimeout(
           () => onUpdateDebounced(values),
@@ -425,11 +426,16 @@ function FormBody({
           <CollapsiblePanel key={name} title={name}>
             {param.map((field) => {
               const fieldName = `${type}.${field.name}` as const;
+              const schema = (
+                field.content
+                  ? field.content[Object.keys(field.content)[0]].schema
+                  : field.schema
+              ) as ParsedSchema;
 
               if (fields?.parameter) {
                 return renderCustomField(
                   fieldName,
-                  field.schema,
+                  schema,
                   fields.parameter,
                   field.name,
                 );
@@ -440,7 +446,7 @@ function FormBody({
                   key={fieldName}
                   name={field.name}
                   fieldName={fieldName}
-                  field={field.schema}
+                  field={schema}
                 />
               );
             })}

packages/openapi/src/playground/fetcher.ts

@@ -30,9 +30,13 @@ export function createBrowserFetcher(
         headers.append('Content-Type', options.bodyMediaType);
 
       for (const key in options.header) {
-        const paramValue = options.header[key];
+        const param = options.header[key];
 
-        if (paramValue.length > 0) headers.append(key, paramValue.toString());
+        if (!Array.isArray(param.value)) {
+          headers.append(key, param.value);
+        } else {
+          headers.append(key, param.value.join(','));
+        }
       }
 
       const proxyUrl = options.proxyUrl
@@ -54,34 +58,19 @@ export function createBrowserFetcher(
             data: `[Fumadocs] No adapter for ${options.bodyMediaType}, you need to specify one from 'createOpenAPI()'.`,
           };
 
-        body = await adapter.encode(options);
+        body = adapter.encode(options as { body: unknown });
       }
 
       // cookies
       for (const key in options.cookie) {
-        const value = options.cookie[key];
-        if (!value) continue;
-
-        const cookie = {
-          [key]: value,
-          domain:
-            proxyUrl && proxyUrl.origin !== window.location.origin
-              ? `domain=${proxyUrl.host}`
-              : undefined,
-          path: '/',
-          'max-age': 30,
-        };
-
-        let str = '';
-        for (const [key, value] of Object.entries(cookie)) {
-          if (value) {
-            if (str.length > 0) str += '; ';
-
-            str += `${key}=${value}`;
-          }
-        }
+        const param = options.cookie[key];
+        const segs: string[] = [`${key}=${param.value}`];
+
+        if (proxyUrl && proxyUrl.origin !== window.location.origin)
+          segs.push(`domain=${proxyUrl.host}`);
+        segs.push('path=/', 'max-age=30');
 
-        document.cookie = str;
+        document.cookie = segs.join('; ');
       }
 
       return fetch(url, {

packages/openapi/src/playground/index.tsx

@@ -1,15 +1,18 @@
 import type {
   MethodInformation,
+  ParameterObject,
   RenderContext,
   SecuritySchemeObject,
 } from '@/types';
-import { getPreferredType, type ParsedSchema } from '@/utils/schema';
+import {
+  getPreferredType,
+  type NoReference,
+  type ParsedSchema,
+} from '@/utils/schema';
 import { type ClientProps } from './client';
 import { ClientLazy } from '@/ui/lazy';
 
-export type ParameterField = {
-  name: string;
-  description?: string;
+export type ParameterField = NoReference<ParameterObject> & {
   schema: ParsedSchema;
   in: 'cookie' | 'header' | 'query' | 'path';
 };
@@ -59,12 +62,13 @@ export async function APIPlayground({
     securities: parseSecurities(method, ctx),
     method: method.method,
     route: path,
-    parameters: method.parameters?.map((v) => ({
-      name: v.name,
-      in: v.in as ParameterField['in'],
-      schema: writeReferences((v.schema ?? true) as ParsedSchema, context),
-      description: v.description,
-    })),
+    parameters: method.parameters?.map(
+      (v) =>
+        ({
+          ...v,
+          schema: writeReferences((v.schema ?? true) as ParsedSchema, context),
+        }) as ParameterField,
+    ),
     body:
       bodyContent && mediaType
         ? ({

packages/openapi/src/render/api-page.tsx

@@ -9,7 +9,7 @@ import {
   processDocument,
   type ProcessedDocument,
 } from '@/utils/process-document';
-import type { defaultAdapters } from '@/media/adapter';
+import { defaultAdapters } from '@/media/adapter';
 
 type ApiPageContextProps = Pick<
   Partial<RenderContext>,
@@ -145,14 +145,7 @@ export async function getContext(
     generateCodeSamples: options.generateCodeSamples,
     servers,
     mediaAdapters: {
-      ...({
-        'application/octet-stream': true,
-        'application/json': true,
-        'multipart/form-data': true,
-        'application/xml': true,
-        'application/x-ndjson': true,
-        'application/x-www-form-urlencoded': true,
-      } satisfies Record<keyof typeof defaultAdapters, true>),
+      ...defaultAdapters,
       ...options.mediaAdapters,
     },
     slugger: new Slugger(),