Fixes and enhancements for array query param handling (#241)

Author: chris48s

demo/examples/openapi-array-query-params.yaml

@@ -0,0 +1,43 @@
+openapi: 3.0.3
+info:
+  version: 1.0.0
+  title: ""
+servers:
+  - url: https://example.com
+paths:
+  /Things:
+    get:
+      summary: View Things
+      parameters:
+        - name: "arrayParam"
+          in: "query"
+          required: false
+          description: "You can pass 0, 1 or 2 occurrences of this in the query string"
+          style: "form"
+          explode: true
+          schema:
+            type: "array"
+            maxItems: 2
+            items:
+              type: "string"
+      responses:
+        "200":
+          description: OK
+  /Stuff:
+    get:
+      summary: View Stuff
+      parameters:
+        - name: "arrayParam"
+          in: "query"
+          required: false
+          description: "You can pass 0, 1 or 2 occurrences of this in the query string"
+          style: "pipeDelimited"
+          explode: false
+          schema:
+            type: "array"
+            maxItems: 2
+            items:
+              type: "string"
+      responses:
+        "200":
+          description: OK

packages/docusaurus-plugin-openapi/src/openapi/types.ts

@@ -179,7 +179,7 @@ export interface ParameterObject {
   allowEmptyValue?: boolean;
   //
   style?: string;
-  explode?: string;
+  explode?: boolean;
   allowReserved?: boolean;
   schema?: SchemaObject;
   example?: any;

packages/docusaurus-theme-openapi/src/theme/ApiDemoPanel/ParamOptions/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React, { useState, useEffect } from "react";
+import React, { useState } from "react";
 
 import { nanoid } from "@reduxjs/toolkit";
 
@@ -21,6 +21,11 @@ interface ParamProps {
   param: Param;
 }
 
+interface Item {
+  id: string;
+  value?: string;
+}
+
 function ParamOption({ param }: ParamProps) {
   if (param.schema?.type === "array" && param.schema.items?.enum) {
     return <ParamMultiSelectFormItem param={param} />;
@@ -161,10 +166,16 @@ function ArrayItem({
 }
 
 function ParamArrayFormItem({ param }: ParamProps) {
-  const [items, setItems] = useState<{ id: string; value?: string }[]>([]);
+  const [items, setItems] = useState<Item[]>([]);
   const dispatch = useTypedDispatch();
 
   function handleAddItem() {
+    if (
+      param?.schema?.maxItems !== undefined &&
+      items.length >= param.schema.maxItems
+    ) {
+      return;
+    }
     setItems((i) => [
       ...i,
       {
@@ -173,7 +184,7 @@ function ParamArrayFormItem({ param }: ParamProps) {
     ]);
   }
 
-  useEffect(() => {
+  function updateItems(items: Array<Item>) {
     const values = items
       .map((item) => item.value)
       .filter((item): item is string => !!item);
@@ -184,12 +195,13 @@ function ParamArrayFormItem({ param }: ParamProps) {
         value: values.length > 0 ? values : undefined,
       })
     );
-  }, [dispatch, items, param]);
+  }
 
   function handleDeleteItem(itemToDelete: { id: string }) {
     return () => {
       const newItems = items.filter((i) => i.id !== itemToDelete.id);
       setItems(newItems);
+      updateItems(newItems);
     };
   }
 
@@ -202,6 +214,7 @@ function ParamArrayFormItem({ param }: ParamProps) {
         return i;
       });
       setItems(newItems);
+      updateItems(newItems);
     };
   }
 
@@ -230,7 +243,14 @@ function ParamArrayFormItem({ param }: ParamProps) {
           </button>
         </div>
       ))}
-      <button className={styles.buttonThin} onClick={handleAddItem}>
+      <button
+        className={styles.buttonThin}
+        onClick={handleAddItem}
+        disabled={
+          param?.schema?.maxItems != null &&
+          items.length >= param.schema.maxItems
+        }
+      >
         Add item
       </button>
     </>

packages/docusaurus-theme-openapi/src/theme/ApiDemoPanel/buildPostmanRequest.test.ts

@@ -0,0 +1,79 @@
+/* ============================================================================
+ * Copyright (c) Cloud Annotations
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import sdk from "postman-collection";
+
+import { openApiQueryParams2PostmanQueryParams } from "./buildPostmanRequest";
+
+describe("openApiQueryParams2PostmanQueryParams", () => {
+  it("should transform empty array to empty array", () => {
+    const expected: sdk.QueryParam[] = [];
+    const actual = openApiQueryParams2PostmanQueryParams([]);
+    expect(actual).toStrictEqual(expected);
+  });
+
+  it("default to comma delimited", () => {
+    const expected: sdk.QueryParam[] = [
+      new sdk.QueryParam({ key: "arrayParam", value: "abc,def" }),
+    ];
+    const actual = openApiQueryParams2PostmanQueryParams([
+      {
+        name: "arrayParam",
+        in: "query",
+        value: ["abc", "def"],
+      },
+    ]);
+    expect(actual).toStrictEqual(expected);
+  });
+
+  it("should expand params if explode=true", () => {
+    const expected: sdk.QueryParam[] = [
+      new sdk.QueryParam({ key: "arrayParam", value: "abc" }),
+      new sdk.QueryParam({ key: "arrayParam", value: "def" }),
+    ];
+    const actual = openApiQueryParams2PostmanQueryParams([
+      {
+        name: "arrayParam",
+        in: "query",
+        style: "form",
+        explode: true,
+        value: ["abc", "def"],
+      },
+    ]);
+    expect(actual).toStrictEqual(expected);
+  });
+
+  it("should respect style=pipeDelimited", () => {
+    const expected: sdk.QueryParam[] = [
+      new sdk.QueryParam({ key: "arrayParam", value: "abc|def" }),
+    ];
+    const actual = openApiQueryParams2PostmanQueryParams([
+      {
+        name: "arrayParam",
+        in: "query",
+        style: "pipeDelimited",
+        value: ["abc", "def"],
+      },
+    ]);
+    expect(actual).toStrictEqual(expected);
+  });
+
+  it("should respect style=spaceDelimited", () => {
+    const expected: sdk.QueryParam[] = [
+      new sdk.QueryParam({ key: "arrayParam", value: "abc%20def" }),
+    ];
+    const actual = openApiQueryParams2PostmanQueryParams([
+      {
+        name: "arrayParam",
+        in: "query",
+        style: "spaceDelimited",
+        value: ["abc", "def"],
+      },
+    ]);
+    expect(actual).toStrictEqual(expected);
+  });
+});

packages/docusaurus-theme-openapi/src/theme/ApiDemoPanel/buildPostmanRequest.ts

@@ -17,19 +17,36 @@ type Param = {
   value?: string | string[];
 } & ParameterObject;
 
-function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
-  postman.url.query.clear();
+export function openApiQueryParams2PostmanQueryParams(
+  queryParams: Param[]
+): sdk.QueryParam[] {
+  let qp = [];
+  for (const param of queryParams) {
+    if (Array.isArray(param.value) && param?.explode === true) {
+      for (const value of param.value) {
+        qp.push({ ...param, value });
+      }
+    } else {
+      qp.push(param);
+    }
+  }
 
-  const qp = queryParams
+  return qp
     .map((param) => {
       if (!param.value) {
         return undefined;
       }
 
+      let delimiter = ",";
+      if (param?.style === "spaceDelimited") {
+        delimiter = "%20";
+      } else if (param?.style === "pipeDelimited") {
+        delimiter = "|";
+      }
       if (Array.isArray(param.value)) {
         return new sdk.QueryParam({
           key: param.name,
-          value: param.value.map(encodeURIComponent).join(","),
+          value: param.value.map(encodeURIComponent).join(delimiter),
         });
       }
 
@@ -50,7 +67,11 @@ function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
       });
     })
     .filter((item): item is sdk.QueryParam => item !== undefined);
+}
 
+function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
+  postman.url.query.clear();
+  const qp = openApiQueryParams2PostmanQueryParams(queryParams);
   if (qp.length > 0) {
     postman.addQueryParams(qp);
   }