feat: support exploded form parameters in docs

fern/apis/fdr/definition/api/latest/type.yml

@@ -118,6 +118,7 @@ types:
     extends: ObjectProperty # has description and availability
     properties:
       contentType: optional<ContentType>
+      exploded: optional<boolean>
 
   FormDataFile:
     extends:

fern/apis/fdr/definition/api/v1/read/endpoint.yml

@@ -237,6 +237,7 @@ types:
       filenames: list<string>
       filenameWithData: FilenameWithData
       filenamesWithData: list<FilenameWithData>
+      exploded: list<unknown>
 
   BytesValue:
     union:

packages/fdr-sdk/src/api-definition/migrators/v1ToV2.ts

@@ -688,6 +688,7 @@ export class ApiDefinitionV1ToLatest {
           contentType: bodyProp.contentType,
           description: bodyProp.description,
           availability: bodyProp.availability,
+          exploded: undefined,
           valueShape: {
             type: "alias",
             value: this.migrateTypeReference(bodyProp.valueType),

packages/fdr-sdk/src/api-definition/snippets/SnippetHttpRequest.ts

@@ -9,6 +9,11 @@ interface SnippetHttpRequestBodyJson {
   value?: unknown;
 }
 
+interface SnippetHttpRequestBodyJsonExploded {
+  type: "exploded";
+  value?: unknown[];
+}
+
 export interface SnippetHttpRequestBodyForm {
   type: "form";
   value: Record<string, SnippetHttpRequestBodyFormValue>;
@@ -27,6 +32,7 @@ export interface SnippetHttpRequestBodyFormValueFilenames {
 
 export type SnippetHttpRequestBodyFormValue =
   | SnippetHttpRequestBodyJson
+  | SnippetHttpRequestBodyJsonExploded
   | SnippetHttpRequestBodyFormValueFilename
   | SnippetHttpRequestBodyFormValueFilenames;
 
@@ -131,6 +137,7 @@ export function toSnippetHttpRequest(
                 toRet[key] = visitDiscriminatedUnion(
                   val
                 )._visit<SnippetHttpRequestBodyFormValue>({
+                  exploded: (value) => value,
                   json: (value) => value,
                   filename: (value) => ({
                     type: "filename",

packages/fdr-sdk/src/api-definition/snippets/curl.test.ts

@@ -320,4 +320,35 @@ describe("curl", () => {
           }'"
         `);
   });
+
+  it("generates request with exploded form parameters", () => {
+    expect(
+      convertToCurl(
+        {
+          method: "POST",
+          url: "https://api.example.com/upload",
+          headers: {
+            "Content-Type": "multipart/form-data",
+          },
+          searchParams: {},
+          body: {
+            type: "form",
+            value: {
+              tags: {
+                type: "exploded",
+                value: ["tag1", "tag2", "tag3"],
+              },
+            },
+          },
+        },
+        { usesApplicationJsonInFormDataValue: false }
+      )
+    ).toMatchInlineSnapshot(`
+          "curl -X POST https://api.example.com/upload \\
+               -H "Content-Type: multipart/form-data" \\
+               -F tags="tag1" \\
+               -F tags="tag2" \\
+               -F tags="tag3""
+        `);
+  });
 });

packages/fdr-sdk/src/api-definition/snippets/curl.ts

@@ -172,6 +172,14 @@ function getBodyFormValueString(
       return getBodyFormValueFilenameString(value, key);
     case "filenames":
       return getBodyFormValueFilenamesStrings(value, key);
+    case "exploded":
+      return (value.value ?? []).flatMap((item) =>
+        getBodyFormValueJsonString(
+          item,
+          key,
+          usesApplicationJsonInFormDataValue
+        )
+      );
     default:
       throw new UnreachableCaseError(value);
   }

packages/fern-docs/ui/src/playground/fetch-utils/requestToBodyInit.ts

@@ -51,6 +51,26 @@ export async function toBodyInit(
               }
             }
             break;
+          case "exploded":
+            for (const item of value.value) {
+              if (item === undefined) {
+                continue;
+              }
+              if (value.contentType === "application/json") {
+                formData.append(
+                  key,
+                  new Blob([JSON.stringify(item)], {
+                    type: "application/json",
+                  })
+                );
+              } else {
+                const finalValue =
+                  typeof item === "string" ? item : JSON.stringify(item);
+
+                formData.append(key, finalValue);
+              }
+            }
+            break;
           default:
             console.error(new UnreachableCaseError(value));
             break;

packages/fern-docs/ui/src/playground/types/serializable.ts

@@ -33,10 +33,17 @@ export const SerializableJsonSchema = z.object({
     .optional(),
 });
 
+export const SerializableExplodedJsonSchema = z.object({
+  type: z.literal("exploded"),
+  value: z.array(z.unknown()),
+  contentType: z.string().optional(),
+});
+
 export const SerializableFormDataEntryValueSchema = z.union([
   SerializableSingleFileSchema,
   SerializableMultipleFilesSchema,
   SerializableJsonSchema,
+  SerializableExplodedJsonSchema,
 ]);
 
 export type SerializableFormDataEntryValue = z.infer<

packages/fern-docs/ui/src/playground/utils/__test__/serialize.test.ts

@@ -0,0 +1,108 @@
+import {
+  HttpRequestBodyShape,
+  PropertyKey,
+  TypeShape,
+} from "@fern-api/fdr-sdk/api-definition";
+import { PlaygroundFormStateBody } from "../../types";
+import { serializeFormStateBody } from "../serialize";
+
+const STRING_VALUE_SHAPE: TypeShape = {
+  type: "alias",
+  value: {
+    type: "primitive",
+    value: {
+      type: "string",
+      format: undefined,
+      regex: undefined,
+      minLength: undefined,
+      maxLength: undefined,
+      default: undefined,
+    },
+  },
+};
+
+describe("serializeFormStateBody", () => {
+  it("handles exploded form data parameters", async () => {
+    const shape: HttpRequestBodyShape = {
+      type: "formData",
+      fields: [
+        {
+          type: "property",
+          key: PropertyKey("tags"),
+          description: undefined,
+          availability: undefined,
+          valueShape: STRING_VALUE_SHAPE,
+          exploded: true,
+          contentType: "application/json",
+        },
+      ],
+      description: undefined,
+      availability: undefined,
+    };
+
+    const body: PlaygroundFormStateBody = {
+      type: "form-data",
+      value: {
+        tags: {
+          type: "json",
+          value: ["tag1", "tag2", "tag3"],
+        },
+      },
+    };
+
+    const result = await serializeFormStateBody(shape, body, true);
+
+    expect(result).toEqual({
+      type: "form-data",
+      value: {
+        tags: {
+          type: "exploded",
+          value: ["tag1", "tag2", "tag3"],
+          contentType: "application/json",
+        },
+      },
+    });
+  });
+
+  it("converts single value to array for exploded parameters", async () => {
+    const shape: HttpRequestBodyShape = {
+      type: "formData",
+      fields: [
+        {
+          type: "property",
+          key: PropertyKey("tag"),
+          valueShape: STRING_VALUE_SHAPE,
+          exploded: true,
+          contentType: "application/json",
+          description: undefined,
+          availability: undefined,
+        },
+      ],
+      description: undefined,
+      availability: undefined,
+    };
+
+    const body: PlaygroundFormStateBody = {
+      type: "form-data",
+      value: {
+        tag: {
+          type: "json",
+          value: "single-tag",
+        },
+      },
+    };
+
+    const result = await serializeFormStateBody(shape, body, true);
+
+    expect(result).toEqual({
+      type: "form-data",
+      value: {
+        tag: {
+          type: "exploded",
+          value: ["single-tag"],
+          contentType: "application/json",
+        },
+      },
+    });
+  });
+});

packages/fern-docs/ui/src/playground/utils/serialize.ts

@@ -53,6 +53,25 @@ export async function serializeFormStateBody(
                 p.key === key && p.type === "property"
             );
 
+            const contentType =
+              compact(flatten([property?.contentType]))[0] ??
+              (usesApplicationJsonInFormDataValue
+                ? "application/json"
+                : undefined);
+
+            if (property?.exploded) {
+              // For exploded form fields, convert value to array if not already
+              const arrayValue = Array.isArray(value.value)
+                ? value.value
+                : [value.value];
+              formDataValue[key] = {
+                type: "exploded",
+                value: arrayValue,
+                contentType,
+              };
+              break;
+            }
+
             // check if the json value is a string and performa a safe parse operation to check if the json is stringified
             if (typeof value.value === "string") {
               value.value = safeParse(value.value);
@@ -62,11 +81,7 @@ export async function serializeFormStateBody(
               ...value,
               // this is a hack to allow the API Playground to send JSON blobs in form data
               // revert this once we have a better solution
-              contentType:
-                compact(flatten([property?.contentType]))[0] ??
-                (usesApplicationJsonInFormDataValue
-                  ? "application/json"
-                  : undefined),
+              contentType,
             };
             break;
           }

packages/parsers/src/openapi/3.1/paths/request/RequestMediaTypeObjectConverter.node.ts

@@ -213,6 +213,7 @@ export class RequestMediaTypeObjectConverterNode extends BaseOpenApiV3_1Converte
                     type,
                     key: FernRegistry.PropertyKey(key),
                     contentType: field.contentType,
+                    exploded: undefined,
                     valueShape,
                     description: field.description,
                     availability: field.availability?.convert(),

packages/template-resolver/package.json

@@ -28,7 +28,7 @@
     "test": "vitest --run --passWithNoTests"
   },
   "dependencies": {
-    "@fern-fern/fdr-cjs-sdk": "0.116.5-873e41db0",
+    "@fern-fern/fdr-cjs-sdk": "0.75.41-28-g8e9080929",
     "prettier": "^3.4.2"
   },
   "devDependencies": {

packages/template-resolver/src/__test__/union.ts

@@ -46,6 +46,7 @@ export const UNIONS_SNIPPET: FernRegistry.EndpointSnippetTemplate = {
                         type: "primitive",
                         value: {
                           type: "string",
+                          format: undefined,
                           regex: undefined,
                           minLength: undefined,
                           maxLength: undefined,