feat(cli): Allow for parameter fields to be overridden

Author: freakyfelt

README.md

@@ -313,6 +313,51 @@ operations:
 
 The goal of the builder is to be a lightweight abstraction on top of OpenAPI, injecting in defaults where it doesn't really matter for services vending an SDK. That being said, the builder does allow you to provide any OpenAPI 3.1 operation definitions you want.
 
+### Adding more properties to parameters
+
+Sometimes you may want to add additional properties to a parameter, such as an example or a deprecation message, or to override its location to be in the `path` or `header`. To do this, you can provide an additional `parameters` key on the input that is keyed by the field names.
+
+For example, you can add a deprecation message to a field:
+
+```yaml
+operations:
+  queries:
+    listWidgets:
+      input:
+        schema: { $ref: '#/components/schemas/ListWidgetsInput' }
+        parameters:
+          status:
+            description: 'Use "statuses" instead'
+            deprecated: true
+      output:
+        schema: { $ref: '#/components/schemas/ListWidgetsOutput' }
+
+      errors: []
+```
+
+<details>
+  <summary>Resulting OpenAPI path specification</summary>
+
+```yaml
+paths:
+  /queries/listWidgets:
+    operationId: listWidgets
+    parameters:
+      - name: status
+        in: query
+        schema: { $ref: '#/components/ListWidgetsInput/properties/status' }
+        description: 'Use "statuses" instead'
+        deprecated: true
+      - name: userId
+        in: query
+        ...
+```
+
+</details>
+
+> **Note**
+> Any fields added will take precedence over the defaults for `in` and `schema`
+
 ### (TODO) Changing the HTTP method and URL
 
 > **Warning**

packages/cli/src/operation-transformer.test.ts

@@ -8,7 +8,7 @@ import {
 	operations,
 } from "./__fixtures__/widgets.fixtures.js";
 import { OperationTransformer } from "./operation-transformer.js";
-import { ReferenceObject, SchemaObject } from "./types/oas.js";
+import { ParameterObject, ReferenceObject, SchemaObject } from "./types/oas.js";
 
 const resolver = {
 	resolve: (ref: ReferenceObject) => {
@@ -43,4 +43,66 @@ test("OperationTransformer#transformQueryOperation", async (t) => {
 		);
 		assert.deepStrictEqual(actual, listUserWidgetsOAS);
 	});
+
+	await t.test(
+		"adds specified overrides to the operation parameter",
+		async () => {
+			const actual = await transformer.transformQueryOperation(
+				"listUserWidgets",
+				{
+					...operations.listUserWidgets,
+					input: {
+						...operations.listUserWidgets.input,
+						parameters: {
+							userId: {
+								in: "path",
+							},
+							status: {
+								deprecated: true,
+								description: 'Use "statuses" instead',
+							},
+							nonExistent: {
+								description: "This parameter does not exist in the OAS",
+							},
+						},
+					},
+				}
+			);
+
+			const expectedByName: Record<string, ParameterObject> =
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				listUserWidgetsOAS.parameters!.reduce(
+					(acc, param) => ({
+						...acc,
+						[(param as ParameterObject).name]: param,
+					}),
+					{}
+				);
+			expectedByName.status = {
+				name: "status",
+				in: "query",
+				description: 'Use "statuses" instead',
+				deprecated: true,
+				schema: {
+					type: "array",
+					items: {
+						$ref: "#/components/schemas/WidgetStatus",
+					},
+				},
+			};
+
+			expectedByName.userId = {
+				...expectedByName.userId,
+				in: "path",
+			};
+
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+			const actualByName = actual.parameters!.reduce(
+				(acc, param) => ({ ...acc, [(param as ParameterObject).name]: param }),
+				{}
+			);
+
+			assert.deepStrictEqual(actualByName, expectedByName);
+		}
+	);
 });

packages/cli/src/operation-transformer.ts

@@ -115,7 +115,7 @@ export class OperationTransformer {
 	async transformQueryInput(
 		input: QueryInputObject
 	): Promise<ParameterObject[]> {
-		const { schema: schemaOrRef } = input;
+		const { schema: schemaOrRef, parameters: parameterOverrides = {} } = input;
 		assert(
 			typeof schemaOrRef === "object",
 			"Query input schema must be an object"
@@ -136,6 +136,7 @@ export class OperationTransformer {
 			in: "query",
 			schema,
 			...(inputSchema?.required?.includes(name) ? { required: true } : {}),
+			...parameterOverrides[name],
 		})) as ParameterObject[];
 	}
 

packages/cli/src/types/operations.ts

@@ -5,7 +5,7 @@ import {
 	ResponsesObject,
 } from "./oas.js";
 
-export type RPCParameterObject = Omit<OASParameterObject, "schema">;
+export type RPCParameterObject = Partial<OASParameterObject>;
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface RPCOutputObject extends MediaTypeObject {}
 
@@ -66,10 +66,8 @@ export interface QueryOperationObject extends RPCOperationObject {
 export interface QueryInputObject extends MediaTypeObject {
 	/**
 	 * Allows for optional overriding of the location of specific parameters
-	 *
-	 * @todo support for non-query locations
 	 */
-	// parameters?: Record<string, RPCParameterObject>;
+	parameters?: Record<string, RPCParameterObject>;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface