openapi3 - support @encode for @query parameters (#6473)

Fixes #6463 

Note - this only actually impacted `@query` for openapi3 since the
special array encodings aren't actually valid for headers to begin with.
However the array encoding formats will be removed now for header
parameters if they were for some reason used.

---------

Co-authored-by: Christopher Radek <[email protected]>

Author: chrisradek

.chronus/changes/oa3-support-encode-query-2025-2-14-15-30-23.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+Adds support for `@encode` to specify array encodings for `@query` parameters

packages/openapi3/src/encoding.ts

@@ -1,10 +1,15 @@
 import { type ModelProperty, Program, type Scalar, getEncode } from "@typespec/compiler";
 import { ObjectBuilder } from "@typespec/compiler/emitter-framework";
-import { isHeader } from "@typespec/http";
+import { isHeader, isQueryParam } from "@typespec/http";
 import type { ResolvedOpenAPI3EmitterOptions } from "./openapi.js";
 import { getSchemaForStdScalars } from "./std-scalar-schemas.js";
 import type { OpenAPI3Schema, OpenAPISchema3_1 } from "./types.js";
 
+function isParameterStyleEncoding(encoding: string | undefined): boolean {
+  if (!encoding) return false;
+  return ["ArrayEncoding.pipeDelimited", "ArrayEncoding.spaceDelimited"].includes(encoding);
+}
+
 export function applyEncoding(
   program: Program,
   typespecType: Scalar | ModelProperty,
@@ -17,6 +22,10 @@ export function applyEncoding(
 
   const encodeData = getEncode(program, typespecType);
   if (encodeData) {
+    // Query parameters have a couple of special cases where encoding ends up as style.
+    if (isQueryParam(program, typespecType) && isParameterStyleEncoding(encodeData.encoding)) {
+      return targetObject;
+    }
     const newType = getSchemaForStdScalars(encodeData.type as any, options);
     targetObject.type = newType.type;
     // If the target already has a format it takes priority. (e.g. int32)

packages/openapi3/src/openapi.ts

@@ -9,6 +9,7 @@ import {
   getAllTags,
   getAnyExtensionFromPath,
   getDoc,
+  getEncode,
   getFormat,
   getMaxItems,
   getMaxLength,
@@ -1415,6 +1416,7 @@ function createOAPIEmitter(
       applyIntrinsicDecorators(param, typeSchema),
       options,
     );
+
     if (param.defaultValue) {
       schema.default = getDefaultValue(program, param.defaultValue, param);
     }
@@ -1510,9 +1512,26 @@ function createOAPIEmitter(
       // For query parameters(style: form) the default is explode: true https://spec.openapis.org/oas/v3.0.2#fixed-fields-9
       attributes.explode = false;
     }
+    const style = getParameterStyle(httpProperty.property);
+    if (style) {
+      attributes.style = style;
+    }
+
     return attributes;
   }
 
+  function getParameterStyle(type: ModelProperty): string | undefined {
+    const encode = getEncode(program, type);
+    if (!encode) return;
+
+    if (encode.encoding === "ArrayEncoding.pipeDelimited") {
+      return "pipeDelimited";
+    } else if (encode.encoding === "ArrayEncoding.spaceDelimited") {
+      return "spaceDelimited";
+    }
+    return;
+  }
+
   function getHeaderParameterAttributes(httpProperty: HttpProperty & { kind: "header" }) {
     const attributes: { style?: "simple"; explode?: boolean } = {};
     if (httpProperty.options.explode) {

packages/openapi3/test/parameters.test.ts

@@ -32,6 +32,23 @@ worksFor(["3.0.0", "3.1.0"], ({ diagnoseOpenApiFor, openApiFor }) => {
       strictEqual(param.name, "$select");
     });
 
+    it.each([
+      { encoding: "ArrayEncoding.pipeDelimited", style: "pipeDelimited" },
+      { encoding: "ArrayEncoding.spaceDelimited", style: "spaceDelimited" },
+    ])("can set style to $style with @encode($encoding)", async ({ encoding, style }) => {
+      const param = await getQueryParam(
+        `op test(@query @encode(${encoding}) myParam: string[]): void;`,
+      );
+      expect(param).toMatchObject({
+        explode: false,
+        style: style,
+      });
+      expect(param.schema).toStrictEqual({
+        type: "array",
+        items: { type: "string" },
+      });
+    });
+
     describe("doesn't set explode if explode: true (Openapi3.0 inverse default)", () => {
       it("with option", async () => {
         const param = await getQueryParam(