adorn-api 1.1.7 → 1.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/adapter/express/coercion.ts

@@ -192,8 +192,18 @@ function coerceArrayValue(
   if (value === undefined || value === null) {
     return { value, ok: true, changed: false };
   }
-  const input = Array.isArray(value) ? value : [value];
-  let changed = !Array.isArray(value);
+  let input: unknown[];
+  let changed: boolean;
+  if (Array.isArray(value)) {
+    input = value;
+    changed = false;
+  } else if (typeof value === "string" && value.includes(",")) {
+    input = value.split(",").map((s) => s.trim());
+    changed = true;
+  } else {
+    input = [value];
+    changed = true;
+  }
   let ok = true;
   const output = input.map((entry) => {
     const result = coerceValue(entry, schema.items, mode);

package/src/core/openapi.ts

@@ -317,13 +317,31 @@ function buildParameters(
   if (!fieldEntries.length) {
     return [];
   }
-  return fieldEntries.map((entry) => ({
-    name: entry.name,
-    in: location,
-    required: location === "path" ? true : entry.required,
-    description: entry.description,
-    schema: buildSchemaFromSource(entry.schema, context)
-  }));
+  return fieldEntries.map((entry) => {
+    const param: Record<string, unknown> = {
+      name: entry.name,
+      in: location,
+      required: location === "path" ? true : entry.required,
+      description: entry.description,
+      schema: buildSchemaFromSource(entry.schema, context)
+    };
+
+    if (location === "query" && isSchemaNode(entry.schema)) {
+      if (entry.schema.kind === "array") {
+        param.style = "form";
+        param.explode = true;
+      } else if (entry.schema.kind === "object") {
+        param.style = "deepObject";
+        param.explode = true;
+      }
+
+      if (entry.schema.examples && entry.schema.examples.length > 0) {
+        param.example = entry.schema.examples[0];
+      }
+    }
+
+    return param;
+  });
 }
 
 function extractFields(

package/tests/unit/openapi-parameters.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { t } from "../../src/core/schema";
+import { registerController, registerDto } from "../../src/core/metadata";
+import { buildOpenApi } from "../../src/core/openapi";
+import { createInputCoercer } from "../../src/adapter/express/coercion";
+
+describe("OpenAPI query parameter serialization", () => {
+  class QueryArrayController {}
+
+  beforeEach(() => {
+    registerController({
+      basePath: "/items",
+      controller: QueryArrayController,
+      routes: [
+        {
+          httpMethod: "get",
+          path: "/",
+          handlerName: "list",
+          query: {
+            schema: {
+              kind: "object",
+              properties: {
+                ids: t.array(t.string()),
+                nums: t.array(t.integer()),
+                tags: t.array(t.string(), { examples: [["a", "b"]] })
+              }
+            }
+          },
+          responses: [{ status: 200 }]
+        }
+      ]
+    });
+  });
+
+  it("query array<string> generates style=form + explode=true", () => {
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [QueryArrayController]
+    });
+
+    const params = (doc.paths["/items"] as any).get.parameters as any[];
+    const idsParam = params.find((p: any) => p.name === "ids");
+
+    expect(idsParam).toBeDefined();
+    expect(idsParam.style).toBe("form");
+    expect(idsParam.explode).toBe(true);
+  });
+
+  it("query array<integer> generates style=form + explode=true", () => {
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [QueryArrayController]
+    });
+
+    const params = (doc.paths["/items"] as any).get.parameters as any[];
+    const numsParam = params.find((p: any) => p.name === "nums");
+
+    expect(numsParam).toBeDefined();
+    expect(numsParam.style).toBe("form");
+    expect(numsParam.explode).toBe(true);
+  });
+
+  it("projects example from schema.examples to parameter.example", () => {
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [QueryArrayController]
+    });
+
+    const params = (doc.paths["/items"] as any).get.parameters as any[];
+    const tagsParam = params.find((p: any) => p.name === "tags");
+
+    expect(tagsParam).toBeDefined();
+    expect(tagsParam.example).toEqual(["a", "b"]);
+  });
+});
+
+describe("Query array coercion – CSV support", () => {
+  it("?ids=1&ids=2 -> [1,2] via repeated keys", () => {
+    const coerce = createInputCoercer(
+      { schema: { kind: "object", properties: { ids: t.array(t.integer()) } } },
+      { mode: "safe", location: "query" }
+    )!;
+
+    const result = coerce({ ids: ["1", "2"] });
+    expect(result.ids).toEqual([1, 2]);
+  });
+
+  it("?ids=1,2 -> [1,2] via CSV string", () => {
+    const coerce = createInputCoercer(
+      { schema: { kind: "object", properties: { ids: t.array(t.integer()) } } },
+      { mode: "safe", location: "query" }
+    )!;
+
+    const result = coerce({ ids: "1,2" });
+    expect(result.ids).toEqual([1, 2]);
+  });
+});