rapidoc 12.0.0 → 12.1.0

package/src/utils/request-utils.js

@@ -157,6 +157,67 @@ export function buildUrlEncodedBody(fields = [], dynamicJson = "") {
   return params;
 }
 
+const isComplexSchema = (schema) =>
+  !!schema &&
+  (schema.type === "object" ||
+    (Array.isArray(schema.type) && schema.type.includes("object")) ||
+    (!schema.type && !!schema.properties));
+
+/**
+ * Content-Type of a multipart/form-data part, following OpenAPI's "Special Considerations for multipart Content":
+ * the encoding object's contentType when the spec gives one (the first of a comma-separated list), application/json
+ * for an object or an array of objects, and "" otherwise (text/plain, or a file's own type).
+ *
+ * @param {object} schema - Schema of the form field
+ * @param {object} [encoding] - The media type's encoding entry for that field
+ * @returns {string}
+ */
+export function multipartPartContentType(schema, encoding) {
+  const declared =
+    typeof encoding?.contentType === "string" ? encoding.contentType.split(",")[0].trim() : "";
+  if (declared) {
+    return declared;
+  }
+  if (isComplexSchema(schema) || (schema?.type === "array" && isComplexSchema(schema.items))) {
+    return "application/json";
+  }
+  return "";
+}
+
+// Quotes and line breaks in part names and file names are percent-encoded, as browsers do for FormData
+const escapePartName = (name) =>
+  String(name).replace(/"/g, "%22").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+
+/**
+ * Serializes FormData into a multipart/form-data body in which parts carry a Content-Type.
+ * A browser only sends a Content-Type for a part that is a file, and a Blob part always gets filename="blob",
+ * which servers read as an upload; so parts with a type in partContentTypes are written by hand.
+ *
+ * @param {FormData} formData
+ * @param {Object<string, string>} partContentTypes - Content-Type per field name, for fields that are not files
+ * @param {string} [boundary]
+ * @returns {{ body: Blob, contentType: string }}
+ */
+export function serializeMultipartBody(
+  formData,
+  partContentTypes = {},
+  boundary = `----RapiDocFormBoundary${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`,
+) {
+  const chunks = [];
+  for (const [name, value] of formData.entries()) {
+    const isFile = typeof value !== "string";
+    let head = `--${boundary}\r\nContent-Disposition: form-data; name="${escapePartName(name)}"`;
+    if (isFile) {
+      head += `; filename="${escapePartName(value.name ?? "blob")}"\r\nContent-Type: ${value.type || partContentTypes[name] || "application/octet-stream"}`;
+    } else if (partContentTypes[name]) {
+      head += `\r\nContent-Type: ${partContentTypes[name]}`;
+    }
+    chunks.push(`${head}\r\n\r\n`, isFile ? value : value.replace(/\r?\n/g, "\r\n"), "\r\n");
+  }
+  chunks.push(`--${boundary}--\r\n`);
+  return { body: new Blob(chunks), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
 /**
  * Builds a FormData instance from structured field entries.
  *

package/src/utils/schema-utils.js

@@ -129,6 +129,23 @@ export function isBinaryFileField(schema) {
   );
 }
 
+// Keywords that only annotate a schema, without telling anything about the type of the value
+const ANNOTATION_KEYWORDS = new Set([
+  "title",
+  "description",
+  "example",
+  "examples",
+  "default",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "externalDocs",
+]);
+
+function isAnnotationOnly(schema) {
+  return Object.keys(schema).every((key) => ANNOTATION_KEYWORDS.has(key) || key.startsWith("x-"));
+}
+
 /* Generates an schema object containing type and constraint info */
 export function getTypeInfo(schema) {
   if (!schema) {
@@ -170,7 +187,7 @@ export function getTypeInfo(schema) {
       }
     });
     dataType = subTypes.length > 0 ? subTypes.join("┃") : "{missing-type-info}";
-  } else if (Object.keys(schema).length === 0) {
+  } else if (isAnnotationOnly(schema)) {
     dataType = "any";
   } else {
     dataType = "{missing-type-info}";
@@ -217,9 +234,7 @@ export function getTypeInfo(schema) {
     html: "",
   };
 
-  if (info.type === "{recursive}") {
-    info.description = schema.$ref.substring(schema.$ref.lastIndexOf("/") + 1);
-  } else if (info.type === "{missing-type-info}" || info.type === "any") {
+  if (info.type === "{missing-type-info}" || info.type === "any") {
     info.description = info.description || "";
   }
   // Set Allowed Values
@@ -1316,8 +1331,8 @@ function createPrimitiveAST(schema, name, isRequired) {
     title: (schema.title || "").trim(),
     required: isRequired,
     deprecated: schema.deprecated || !!typeInfo.deprecated,
-    readOnly: schema.readOnly || typeInfo.readOrWriteOnly === "readonly",
-    writeOnly: schema.writeOnly || typeInfo.readOrWriteOnly === "writeonly",
+    readOnly: schema.readOnly || typeInfo.readOrWriteOnly === "🆁",
+    writeOnly: schema.writeOnly || typeInfo.readOrWriteOnly === "🆆",
     html: typeInfo.html || "",
   };
 }
@@ -1502,6 +1517,10 @@ function composeSchemaAST(schema, level, name, isRequired, suffix) {
           optAst.writeOnly = false;
           optAst.optionIndex = idx + 1;
           optAst.optionTitle = optTitle;
+          if (optAst.kind === "primitive" && !optTitle) {
+            // The OPT n badge already names it, a row labelled "Option n" would only repeat it
+            optAst.name = "";
+          }
         }
         return optAst;
       })
@@ -1877,6 +1896,14 @@ function getSerializeStyleForContentType(contentType) {
   return null;
 }
 
+/**
+ * Text that names an example in an examples dropdown: its summary, or its key when it has none.
+ * A long summary is shown whole; the dropdown wraps it, or cuts it where the browser's select can't wrap.
+ */
+export function exampleLabel(example) {
+  return example?.exampleSummary || example?.exampleId || "";
+}
+
 export function getSchemaFromParam(param) {
   if (param.schema) {
     return [param.schema, null, null];

package/src/utils/slugger.js

@@ -129,23 +129,21 @@ export class OperationSlugger {
       return this.opMap.get(opKey);
     }
 
-    let candidate = this.slugOp(op);
+    // Hierarchical style prefixes with tag if provided; `used` holds the prefixed slugs
+    const prefix = tagSlug && tagSlug !== "general" ? `${tagSlug}--` : "";
+    const base = this.slugOp(op);
+    let candidate = `${prefix}${base}`;
 
     // Smart semantic collision differentiator:
     // If the base candidate has already been seen in this spec, attempt method-prefix first (e.g. post-webhooks)
     if (this.used.has(candidate)) {
       const method = (op.method || "get").toLowerCase();
-      const methodCandidate = `${method}-${candidate}`;
+      const methodCandidate = `${prefix}${method}-${base}`;
       if (!this.used.has(methodCandidate)) {
         candidate = methodCandidate;
       }
     }
 
-    // Hierarchical style prefixes with tag if provided
-    if (tagSlug && tagSlug !== "general") {
-      candidate = `${tagSlug}--${candidate}`;
-    }
-
     // Guaranteed uniqueness via GitHub slugger registry
     const finalSlug = this.slugger.slug(candidate);
     this.used.add(finalSlug);

package/src/utils/spec-parser.js

@@ -169,6 +169,7 @@ export default async function ProcessSpec(
   matchPaths = "",
   matchType = "",
   removeEndpointsWithBadgeLabelAs = "",
+  showUnusedTags = false,
 ) {
   let jsonParsedSpec;
   try {
@@ -274,139 +275,163 @@ export default async function ProcessSpec(
     };
   }
 
-  const hasTagGroups = Boolean(
-    (jsonParsedSpec?.["x-tagGroups"] && jsonParsedSpec["x-tagGroups"].length > 0) ||
-    (jsonParsedSpec?.["x-tag-groups"] && jsonParsedSpec["x-tag-groups"].length > 0),
-  );
+  // Everything after loading is also guarded: a spec that parses but trips the grouping code
+  // (a server without `url`, a tag without `name`, ...) still yields a `specLoadError` result
+  try {
+    const hasTagGroups = Boolean(
+      (jsonParsedSpec?.["x-tagGroups"] && jsonParsedSpec["x-tagGroups"].length > 0) ||
+      (jsonParsedSpec?.["x-tag-groups"] && jsonParsedSpec["x-tag-groups"].length > 0),
+    );
 
-  // Tags with Paths and WebHooks
-  const tags = groupByTags(
-    jsonParsedSpec,
-    sortEndpointsBy,
-    generateMissingTags,
-    sortTags,
-    hasTagGroups,
-  );
+    // Tags with Paths and WebHooks
+    const tags = groupByTags(
+      jsonParsedSpec,
+      sortEndpointsBy,
+      generateMissingTags,
+      sortTags,
+      hasTagGroups,
+      showUnusedTags,
+    );
 
-  // 3-Level Tag Groups (x-tagGroups / x-tag-groups)
-  const tagGroups = groupByTagGroups(jsonParsedSpec, tags);
-
-  // Components
-  const components = getComponents(jsonParsedSpec, sortSchemas);
-
-  // Info Description Headers
-  const infoDescriptionHeaders = jsonParsedSpec.info?.description
-    ? getHeadersFromMarkdown(jsonParsedSpec.info.description)
-    : [];
-
-  // Security Scheme
-  const securitySchemes = [];
-  if (jsonParsedSpec.components?.securitySchemes) {
-    const securitySchemeSet = new Set();
-    Object.entries(jsonParsedSpec.components.securitySchemes).forEach((kv) => {
-      if (!securitySchemeSet.has(kv[0])) {
-        securitySchemeSet.add(kv[0]);
-        const securityObj = { securitySchemeId: kv[0], ...kv[1] };
-        securityObj.in = "header";
-        securityObj.name = "Authorization"; // Name of the header/cookie/api-key
-        securityObj.nameId = kv[1].name || kv[0]; // Name of the security-scheme
-        securityObj.user = "";
-        securityObj.password = "";
-        securityObj.clientId = "";
-        securityObj.clientSecret = "";
-        securityObj.value = "";
-        securityObj.finalKeyValue = "";
-        if (kv[1].type === "apiKey") {
-          securityObj.in = kv[1].in || "header";
-          securityObj.name = kv[1].name || "Authorization";
-        }
-        securitySchemes.push(securityObj);
-      }
-    });
-  }
+    // 3-Level Tag Groups (x-tagGroups / x-tag-groups)
+    const tagGroups = groupByTagGroups(jsonParsedSpec, tags);
 
-  if (attrApiKey && attrApiKeyLocation && attrApiKeyValue) {
-    securitySchemes.push({
-      securitySchemeId: rapidocApiKey,
-      description: "api-key provided in rapidoc element attributes",
-      type: "apiKey",
-      oAuthFlow: "",
-      name: attrApiKey, // Name of the header/cookie/api-key
-      nameId: attrApiKey, // Name of the security-scheme
-      in: attrApiKeyLocation,
-      value: attrApiKeyValue,
-      finalKeyValue: attrApiKeyValue,
-    });
-  }
+    // Components
+    const components = getComponents(jsonParsedSpec, sortSchemas);
 
-  // Updated Security Type Display Text based on Type
-  securitySchemes.forEach((v) => {
-    if (v.type === "http") {
-      v.typeDisplay = v.scheme === "basic" ? "HTTP Basic" : `HTTP Bearer ${v.nameId}`;
-    } else if (v.type === "apiKey") {
-      v.typeDisplay = `API Key (${v.name})`;
-    } else if (v.type === "oauth2") {
-      v.typeDisplay = `OAuth (${v.securitySchemeId})`;
-    } else {
-      v.typeDisplay = v.type || "None";
-    }
-  });
+    // Info Description Headers
+    const infoDescriptionHeaders = jsonParsedSpec.info?.description
+      ? getHeadersFromMarkdown(jsonParsedSpec.info.description)
+      : [];
 
-  // Servers
-  let servers = [];
-  if (
-    jsonParsedSpec.servers &&
-    Array.isArray(jsonParsedSpec.servers) &&
-    jsonParsedSpec.servers.length > 0
-  ) {
-    jsonParsedSpec.servers.forEach((v) => {
-      let computedUrl = v.url.trim();
-      if (
-        !(
-          computedUrl.startsWith("http") ||
-          computedUrl.startsWith("//") ||
-          computedUrl.startsWith("{")
-        )
-      ) {
-        if (typeof window !== "undefined" && window.location?.origin?.startsWith("http")) {
-          v.url = window.location.origin + v.url;
-          computedUrl = v.url;
+    // Security Scheme
+    const securitySchemes = [];
+    if (jsonParsedSpec.components?.securitySchemes) {
+      const securitySchemeSet = new Set();
+      Object.entries(jsonParsedSpec.components.securitySchemes).forEach((kv) => {
+        if (!securitySchemeSet.has(kv[0])) {
+          securitySchemeSet.add(kv[0]);
+          const securityObj = { securitySchemeId: kv[0], ...kv[1] };
+          securityObj.in = "header";
+          securityObj.name = "Authorization"; // Name of the header/cookie/api-key
+          securityObj.nameId = kv[1].name || kv[0]; // Name of the security-scheme
+          securityObj.user = "";
+          securityObj.password = "";
+          securityObj.clientId = "";
+          securityObj.clientSecret = "";
+          securityObj.value = "";
+          securityObj.finalKeyValue = "";
+          if (kv[1].type === "apiKey") {
+            securityObj.in = kv[1].in || "header";
+            securityObj.name = kv[1].name || "Authorization";
+          }
+          securitySchemes.push(securityObj);
         }
+      });
+    }
+
+    if (attrApiKey && attrApiKeyLocation && attrApiKeyValue) {
+      securitySchemes.push({
+        securitySchemeId: rapidocApiKey,
+        description: "api-key provided in rapidoc element attributes",
+        type: "apiKey",
+        oAuthFlow: "",
+        name: attrApiKey, // Name of the header/cookie/api-key
+        nameId: attrApiKey, // Name of the security-scheme
+        in: attrApiKeyLocation,
+        value: attrApiKeyValue,
+        finalKeyValue: attrApiKeyValue,
+      });
+    }
+
+    // Updated Security Type Display Text based on Type
+    securitySchemes.forEach((v) => {
+      if (v.type === "http") {
+        v.typeDisplay = v.scheme === "basic" ? "HTTP Basic" : `HTTP Bearer ${v.nameId}`;
+      } else if (v.type === "apiKey") {
+        v.typeDisplay = `API Key (${v.name})`;
+      } else if (v.type === "oauth2") {
+        v.typeDisplay = `OAuth (${v.securitySchemeId})`;
+      } else {
+        v.typeDisplay = v.type || "None";
       }
-      // Apply server-variables to generate final computed-url
-      if (v.variables) {
-        Object.entries(v.variables).forEach((kv) => {
-          const regex = new RegExp(`{${kv[0]}}`, "g");
-          computedUrl = computedUrl.replace(regex, kv[1].default || "");
-          kv[1].value = kv[1].default || "";
-        });
-      }
-      v.computedUrl = computedUrl;
     });
-    if (serverUrl) {
-      jsonParsedSpec.servers.push({ url: serverUrl, computedUrl: serverUrl });
+
+    // Servers
+    let servers = [];
+    if (
+      jsonParsedSpec.servers &&
+      Array.isArray(jsonParsedSpec.servers) &&
+      jsonParsedSpec.servers.length > 0
+    ) {
+      jsonParsedSpec.servers.forEach((v) => {
+        let computedUrl = String(v.url ?? "").trim();
+        if (
+          !(
+            computedUrl.startsWith("http") ||
+            computedUrl.startsWith("//") ||
+            computedUrl.startsWith("{")
+          )
+        ) {
+          if (typeof window !== "undefined" && window.location?.origin?.startsWith("http")) {
+            v.url = window.location.origin + v.url;
+            computedUrl = v.url;
+          }
+        }
+        // Apply server-variables to generate final computed-url
+        if (v.variables) {
+          Object.entries(v.variables).forEach((kv) => {
+            const regex = new RegExp(`{${kv[0]}}`, "g");
+            computedUrl = computedUrl.replace(regex, kv[1].default || "");
+            kv[1].value = kv[1].default || "";
+          });
+        }
+        v.computedUrl = computedUrl;
+      });
+      if (serverUrl) {
+        jsonParsedSpec.servers.push({ url: serverUrl, computedUrl: serverUrl });
+      }
+    } else if (serverUrl) {
+      jsonParsedSpec.servers = [{ url: serverUrl, computedUrl: serverUrl }];
+    } else if (typeof window !== "undefined" && window.location?.origin?.startsWith("http")) {
+      jsonParsedSpec.servers = [
+        { url: window.location.origin, computedUrl: window.location.origin },
+      ];
+    } else {
+      jsonParsedSpec.servers = [{ url: "http://localhost", computedUrl: "http://localhost" }];
     }
-  } else if (serverUrl) {
-    jsonParsedSpec.servers = [{ url: serverUrl, computedUrl: serverUrl }];
-  } else if (typeof window !== "undefined" && window.location?.origin?.startsWith("http")) {
-    jsonParsedSpec.servers = [{ url: window.location.origin, computedUrl: window.location.origin }];
-  } else {
-    jsonParsedSpec.servers = [{ url: "http://localhost", computedUrl: "http://localhost" }];
+    servers = jsonParsedSpec.servers;
+    const parsedSpec = {
+      specLoadError: false,
+      isSpecLoading: false,
+      info: jsonParsedSpec.info,
+      infoDescriptionHeaders,
+      tags,
+      tagGroups,
+      components,
+      externalDocs: jsonParsedSpec.externalDocs,
+      securitySchemes,
+      servers,
+    };
+    return parsedSpec;
+  } catch (err) {
+    console.info(
+      "RapiDoc: %c There was an issue while processing the spec %o ",
+      "color:orangered",
+      err,
+    );
+    return {
+      specLoadError: true,
+      isSpecLoading: false,
+      info: {
+        title: "Error processing the spec",
+        description: `Unable to process the spec ┃ ${err?.message || err}`,
+        version: "",
+      },
+      tags: [],
+      tagGroups: [],
+    };
   }
-  servers = jsonParsedSpec.servers;
-  const parsedSpec = {
-    specLoadError: false,
-    isSpecLoading: false,
-    info: jsonParsedSpec.info,
-    infoDescriptionHeaders,
-    tags,
-    tagGroups,
-    components,
-    externalDocs: jsonParsedSpec.externalDocs,
-    securitySchemes,
-    servers,
-  };
-  return parsedSpec;
 }
 
 function filterPaths(
@@ -615,6 +640,7 @@ function groupByTags(
   generateMissingTags = false,
   sortTags = false,
   hasTagGroups = false,
+  showUnusedTags = false,
 ) {
   const supportedMethods = [
     "get",
@@ -645,45 +671,37 @@ function groupByTags(
         }))
       : [];
 
-  const pathsAndWebhooks = openApiSpec.paths || {};
-  if (openApiSpec.webhooks) {
-    for (const [key, value] of Object.entries(openApiSpec.webhooks)) {
-      value._type = "webhook";
-      pathsAndWebhooks[key] = value;
-    }
-  }
+  // Paths first, then webhooks; a webhook named like a path does not replace it and the spec is not mutated
+  const pathsAndWebhooks = [
+    ...Object.entries(openApiSpec.paths || {}).map(([name, item]) => [name, item, false]),
+    ...Object.entries(openApiSpec.webhooks || {}).map(([name, item]) => [name, item, true]),
+  ];
   // For each path find the tag and push it into the corresponding tag
-  for (const pathOrHookName in pathsAndWebhooks) {
-    const commonParams = pathsAndWebhooks[pathOrHookName].parameters;
+  for (const [pathOrHookName, pathItem, isWebhook] of pathsAndWebhooks) {
+    const commonParams = pathItem.parameters;
     const commonPathProp = {
-      servers: pathsAndWebhooks[pathOrHookName].servers || [],
-      parameters: pathsAndWebhooks[pathOrHookName].parameters || [],
+      servers: pathItem.servers || [],
+      parameters: pathItem.parameters || [],
     };
-    const isWebhook = pathsAndWebhooks[pathOrHookName]._type === "webhook";
     const operationsToProcess = [];
     supportedMethods.forEach((methodName) => {
-      if (pathsAndWebhooks[pathOrHookName][methodName]) {
+      if (pathItem[methodName]) {
         operationsToProcess.push({
           methodName,
-          pathOrHookObj: pathsAndWebhooks[pathOrHookName][methodName],
+          pathOrHookObj: pathItem[methodName],
         });
       }
     });
 
-    if (
-      pathsAndWebhooks[pathOrHookName].additionalOperations &&
-      typeof pathsAndWebhooks[pathOrHookName].additionalOperations === "object"
-    ) {
-      Object.entries(pathsAndWebhooks[pathOrHookName].additionalOperations).forEach(
-        ([customMethod, customObj]) => {
-          if (customObj && typeof customObj === "object") {
-            operationsToProcess.push({
-              methodName: customMethod.toLowerCase(),
-              pathOrHookObj: customObj,
-            });
-          }
-        },
-      );
+    if (pathItem.additionalOperations && typeof pathItem.additionalOperations === "object") {
+      Object.entries(pathItem.additionalOperations).forEach(([customMethod, customObj]) => {
+        if (customObj && typeof customObj === "object") {
+          operationsToProcess.push({
+            methodName: customMethod.toLowerCase(),
+            pathOrHookObj: customObj,
+          });
+        }
+      });
     }
 
     operationsToProcess.forEach(({ methodName, pathOrHookObj }) => {
@@ -709,7 +727,7 @@ function groupByTags(
         let specTagsItem;
 
         if (openApiSpec.tags) {
-          specTagsItem = openApiSpec.tags.find((v) => v.name.toLowerCase() === tag.toLowerCase());
+          specTagsItem = openApiSpec.tags.find((v) => v.name?.toLowerCase() === tag.toLowerCase());
         }
 
         tagObj = tags.find((v) => v.name === tag);
@@ -816,23 +834,31 @@ function groupByTags(
           xBadges: pathOrHookObj["x-badges"] || undefined,
           xCodeSamples: pathOrHookObj["x-codeSamples"] || pathOrHookObj["x-code-samples"] || "",
           rawOperation: pathOrHookObj,
-          xMcp: pathOrHookObj["x-mcp"] || pathOrHookObj["x-mcp-tool"] || undefined,
-          xInternal:
-            pathOrHookObj["x-internal"] ??
-            pathsAndWebhooks[pathOrHookName]?.["x-internal"] ??
-            undefined,
-          xHidden:
-            pathOrHookObj["x-hidden"] ??
-            pathsAndWebhooks[pathOrHookName]?.["x-hidden"] ??
-            undefined,
-          xOpenAiIsConsequential: pathOrHookObj["x-openai-isConsequential"],
-          xSpeakeasyNameOverride: pathOrHookObj["x-speakeasy-name-override"] || undefined,
+          xInternal: pathOrHookObj["x-internal"] ?? pathItem?.["x-internal"] ?? undefined,
+          xHidden: pathOrHookObj["x-hidden"] ?? pathItem?.["x-hidden"] ?? undefined,
         });
       }); // End of tag path create
     }); // End of operationsToProcess
   }
 
-  const tagsWithSortedPaths = tags.filter((tag) => tag.paths && tag.paths.length > 0);
+  // A tag no operation uses is dropped, unless it has a description to show (a guide or concepts section) and
+  // either show-unused-tags is on or the spec lists the tag in x-tagGroups. Such a tag is marked descriptionOnly.
+  const tagNamesInGroups = new Set(
+    (openApiSpec["x-tagGroups"] || openApiSpec["x-tag-groups"] || [])
+      .flatMap((g) => (Array.isArray(g?.tags) ? g.tags : []))
+      .filter((name) => typeof name === "string")
+      .map((name) => name.toLowerCase()),
+  );
+  const tagsWithSortedPaths = tags.filter((tag) => {
+    if (tag.paths && tag.paths.length > 0) {
+      return true;
+    }
+    if (tag.description && (showUnusedTags || tagNamesInGroups.has(tag.name?.toLowerCase()))) {
+      tag.descriptionOnly = true;
+      return true;
+    }
+    return false;
+  });
   tagsWithSortedPaths.forEach((tag) => {
     if (sortEndpointsBy !== "none") {
       if (sortEndpointsBy === "method") {

package/src/utils/url-utils.js

@@ -20,6 +20,29 @@ export function replacePathParams(pathTemplate = "", pathParams = {}) {
   return resolvedPath;
 }
 
+/**
+ * A value typed into an array input is a string; in a JSON array, numbers and booleans keep their JSON type.
+ */
+function typedArrayItem(value, itemType) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  // an OpenAPI 3.1 type list such as ["integer", "null"] arrives as "integer,null"
+  const types = String(itemType).split(",");
+  const text = value.trim();
+  if (
+    (types.includes("integer") || types.includes("number")) &&
+    text !== "" &&
+    Number.isFinite(Number(text))
+  ) {
+    return Number(text);
+  }
+  if (types.includes("boolean") && (text === "true" || text === "false")) {
+    return text === "true";
+  }
+  return value;
+}
+
 /**
  * Serializes a single query parameter into an array of [key, value] tuples based on OpenAPI style and explode rules.
  */
@@ -29,6 +52,7 @@ export function serializeQueryParam(name, rawValue, options = {}) {
     explode = style === "form",
     isArray = Array.isArray(rawValue),
     isObject = false,
+    itemType = "",
   } = options;
 
   if (rawValue === undefined || rawValue === null || rawValue === "") {
@@ -95,6 +119,10 @@ export function serializeQueryParam(name, rawValue, options = {}) {
       return [];
     }
 
+    // A parameter described by content: application/json is one JSON array, not one parameter per value
+    if (style === "json") {
+      return [[name, JSON.stringify(vals.map((v) => typedArrayItem(v, itemType)))]];
+    }
     if (style === "spaceDelimited") {
       return [[name, vals.join(" ")]];
     }
@@ -140,9 +168,16 @@ export function buildQueryString(queryParams = []) {
       allowReserved = false,
       isArray = false,
       isObject = false,
+      itemType = "",
     } = param;
 
-    const entries = serializeQueryParam(name, value, { style, explode, isArray, isObject });
+    const entries = serializeQueryParam(name, value, {
+      style,
+      explode,
+      isArray,
+      isObject,
+      itemType,
+    });
 
     for (const [k, v] of entries) {
       const encodedKey = encodeURIComponent(k);