feat(cli): allow for overriding the status code and description

Author: freakyfelt

README.md

@@ -358,6 +358,51 @@ paths:
 > **Note**
 > Any fields added will take precedence over the defaults for `in` and `schema`
 
+### Changing the response status code and description
+
+By default the response status code will be an HTTP 200 with a description of "OK". You can customize these in the `output`, e.g. for describing what "success" means or using a more appropriate response status code.
+
+```yaml
+operations:
+  mutations:
+    createWidget:
+      description: Creates the specified widget
+
+      input:
+        schema: { $ref: '#/components/schemas/CreateWidgetInput' }
+      output:
+        description: Widget created without issue
+        statusCode: 201
+        schema: { $ref: '#/components/schemas/Widget' }
+      errors:
+        400: { $ref: '#/components/responses/BadRequest' }
+        404: { $ref: '#/components/responses/NotFound' }
+```
+
+This will result in the following paths object:
+
+<details>
+  <summary>Resulting OpenAPI paths</summary>
+
+```yaml
+paths:
+  /mutations/createWidget:
+    post:
+      operationId: createWidget
+      requestBody:
+        application/json:
+          schema: { $ref: '#/components/schemas/CreateWidgetInput' }
+      responses:
+        201:
+          description: Widget created without issue
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Widget' }
+        400: { $ref: '#/components/responses/BadRequest' }
+        404: { $ref: '#/components/responses/NotFound' }
+```
+</details>
+
 ### (TODO) Changing the HTTP method and URL
 
 > **Warning**

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

@@ -155,4 +155,35 @@ test("OperationTransformer#transformQueryOperation", async (t) => {
 			assert.deepStrictEqual(actualByName, expectedByName);
 		}
 	);
+
+	await t.test(
+		"allows for overriding the successful response status code and description",
+		async () => {
+			const actual = await transformer.transformQueryOperation(
+				"listUserWidgets",
+				{
+					...operations.listUserWidgets,
+					method: "post",
+					path: "/widgets",
+					output: {
+						...operations.listUserWidgets.output,
+						statusCode: 418,
+						description: "I'm a teapot",
+					},
+				}
+			);
+
+			const expectedResponseLength =
+				Object.keys(listUserWidgetsOAS.responses).length + 1;
+			assert.equal(Object.keys(actual.responses), expectedResponseLength);
+			assert.strictEqual(actual.responses["418"], {
+				description: "I'm a teapot",
+				content: {
+					418: {
+						"application/json": operations.listUserWidgets.output,
+					},
+				},
+			});
+		}
+	);
 });

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

@@ -125,21 +125,23 @@ export class OperationTransformer {
 	}
 
 	private transformOperationResponses(
-		output?: RPCOutputObject,
-		errors?: ResponsesObject
+		output: RPCOutputObject = {},
+		errors: ResponsesObject = {}
 	): OperationObject["responses"] {
-		const successResponse = output
-			? {
-					description: "OK",
-					content: {
-						"application/json": output,
-					},
-			  }
-			: DEFAULT_RESPONSE;
+		const { description = "OK", statusCode = 200, ...mediaType } = output;
+
+		const successResponse =
+			Object.keys(mediaType).length > 0
+				? {
+						description,
+						content: {
+							"application/json": mediaType,
+						},
+				  }
+				: DEFAULT_RESPONSE;
 
 		return {
-			// @todo support other status codes
-			200: successResponse,
+			[statusCode]: successResponse,
 			...errors,
 		};
 	}

packages/cli/src/types/operations.ts

@@ -1,5 +1,6 @@
 import { ParameterLocation } from "openapi3-ts/oas31.js";
 import {
+	HttpMethod,
 	MediaTypeObject,
 	ParameterObject as OASParameterObject,
 	OperationObject,
@@ -32,10 +33,24 @@ export interface RPCInputObject extends MediaTypeObject {
 	parameters?: RPCParametersObject;
 }
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface RPCOutputObject extends MediaTypeObject {}
+export interface RPCOutputObject extends MediaTypeObject {
+	/**
+	 * Description of what success means for this operation
+	 *
+	 * This field will be mapped to the `description` field of the `200` response
+	 */
+	description?: string;
+	/**
+	 * Allows for overriding the default "200" status code
+	 */
+	statusCode?: number;
+}
 
 export interface RPCOperationObject
 	extends Omit<OperationObject, "operationId" | "requestBody" | "responses"> {
+	method?: HttpMethod;
+	path?: string;
+
 	/**
 	 * The input object for the operation
 	 *