feat(openapi): multiple success response support (#490)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added support for handling multiple success status codes and complex
response structures in OpenAPI generation when using detailed output
mode.
- Introduced a utility function to flatten nested union schemas for
better schema processing.

- **Bug Fixes**
- Improved validation and error messages for invalid or duplicate status
codes in detailed output structures.

- **Documentation**
- Enhanced documentation for input/output structure options and route
configuration with clearer explanations and richer examples.

- **Tests**
- Expanded test coverage for input/output merging, custom status codes,
headers, error scenarios, and union schema expansion in
encoding/decoding and OpenAPI generation.

- **Refactor**
- Improved internal validation logic for detailed output structures and
encapsulated it in a dedicated method.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/docs/openapi/input-output-structure.md

@@ -9,12 +9,11 @@ oRPC allows you to control the organization of request inputs and response outpu
 
 ## Input Structure
 
-The `inputStructure` option defines how the incoming request data is structured. You can choose between two modes:
+The `inputStructure` option defines how the incoming request data is structured.
 
-- **compact** (default): Merges path parameters with either the query or body data (depending on the HTTP method) into a single object.
-- **detailed**: Separates the request into distinct objects for `params`, `query`, `headers`, and `body`.
+### Compact Mode (default)
 
-### Compact Mode
+Combines path parameters with query or body data (depending on the HTTP method) into a single object.
 
 ```ts
 const compactMode = os.route({
@@ -29,6 +28,13 @@ const compactMode = os.route({
 
 ### Detailed Mode
 
+Provide an object whose fields correspond to each part of the request:
+
+- `params`: Path parameters (`Record<string, string> | undefined`)
+- `query`: Query string data (`any`)
+- `headers`: Headers (`Record<string, string | string[] | undefined>`)
+- `body`: Body data (`any`)
+
 ```ts
 const detailedMode = os.route({
   path: '/ping/{name}',
@@ -43,27 +49,13 @@ const detailedMode = os.route({
   }))
 ```
 
-When using **detailed** mode, the input object adheres to the following structure:
-
-```ts
-export type DetailedInput = {
-  params: Record<string, string> | undefined
-  query: any
-  body: any
-  headers: Record<string, string | string[] | undefined>
-}
-```
-
-Ensure your input schema matches this structure when detailed mode is enabled.
-
 ## Output Structure
 
-The `outputStructure` option determines the format of the response data. There are two modes:
+The `outputStructure` option determines the format of the response based on the output data.
 
-- **compact** (default): Returns only the body data directly.
-- **detailed**: Returns an object with separate `headers` and `body` fields. The headers you provide are merged into the final HTTP response headers.
+### Compact Mode (default)
 
-### Compact Mode
+Returns the output data directly as the response body.
 
 ```ts
 const compactMode = os
@@ -74,6 +66,12 @@ const compactMode = os
 
 ### Detailed Mode
 
+Returns an object with these optional properties:
+
+- `status`: The response status (must be in 200-399 range) if not set fallback to `successStatus`.
+- `headers`: Custom headers to merge with the response headers (`Record<string, string | string[] | undefined>`).
+- `body`: The response body.
+
 ```ts
 const detailedMode = os
   .route({ outputStructure: 'detailed' })
@@ -83,19 +81,34 @@ const detailedMode = os
       body: { message: 'Hello, world!' },
     }
   })
-```
 
-When using **detailed** mode, the output object follows this structure:
+const multipleStatus = os
+  .route({ outputStructure: 'detailed' })
+  .output(z.union([ // for openapi spec generator
+    z.object({
+      status: z.literal(201).describe('record created'),
+      body: z.string()
+    }),
+    z.object({
+      status: z.literal(200).describe('record updated'),
+      body: z.string()
+    }),
+  ]))
+  .handler(async ({ input }) => {
+    if (something) {
+      return {
+        status: 201,
+        body: 'created',
+      }
+    }
 
-```ts
-export type DetailedOutput = {
-  headers: Record<string, string | string[] | undefined>
-  body: any
-}
+    return {
+      status: 200,
+      body: 'updated',
+    }
+  })
 ```
 
-Make sure your handler’s return value matches this structure when using detailed mode.
-
 ## Initial Configuration
 
 Customize the initial oRPC input/output structure settings using `.$route`:

packages/contract/src/route.ts

@@ -54,6 +54,7 @@ export interface Route {
 
   /**
    * The status code of the response when the procedure is successful.
+   * The status code must be in the 200-399 range.
    * This option is typically relevant when integrating with OpenAPI.
    *
    * @see {@link https://orpc.unnoq.com/docs/openapi/routing OpenAPI Routing Docs}
@@ -98,16 +99,18 @@ export interface Route {
    * Determines how the response should be structured based on the output.
    *
    * @option 'compact'
-   * Includes only the body data, encoded directly in the response.
+   * The output data is directly returned as the response body.
    *
    * @option 'detailed'
-   * Separates the output into `headers` and `body` fields.
-   * - `headers`: Custom headers to merge with the response headers.
-   * - `body`: The response data.
+   * Return an object with optional properties:
+   * - `status`: The response status (must be in 200-399 range) if not set fallback to `successStatus`.
+   * - `headers`: Custom headers to merge with the response headers (`Record<string, string | string[] | undefined>`)
+   * - `body`: The response body.
    *
    * Example:
    * ```ts
    * const output = {
+   *   status: 201,
    *   headers: { 'x-custom-header': 'value' },
    *   body: { message: 'Hello, world!' },
    * };

packages/openapi-client/src/adapters/standard/openapi-link-codec.test.ts

@@ -334,7 +334,12 @@ describe('standardOpenapiLinkCodecOptions', () => {
         status: 201,
       }, { context: {}, signal }, ['ping'])
 
-      expect((output as any).headers).toEqual({ 'x-custom': 'value' })
+      expect(output).toEqual({
+        status: 201,
+        headers: { 'x-custom': 'value' },
+        body: deserialize.mock.results[0]!.value,
+      })
+
       expect((output as any).body).toBe(deserialize.mock.results[0]!.value)
 
       expect(deserialize).toHaveBeenCalledTimes(1)

packages/openapi-client/src/adapters/standard/openapi-link-codec.ts

@@ -240,6 +240,7 @@ export class StandardOpenapiLinkCodec<T extends ClientContext> implements Standa
     }
 
     return {
+      status: response.status,
       headers: response.headers,
       body: deserialized,
     }

packages/openapi/src/adapters/standard/openapi-codec.test.ts

@@ -18,7 +18,7 @@ describe('standardOpenAPICodec', () => {
   describe('.decode', () => {
     describe('with compact structure', () => {
       it('with GET method', async () => {
-        serializer.deserialize.mockReturnValueOnce('__deserialized__')
+        serializer.deserialize.mockReturnValueOnce(undefined)
 
         const url = new URL('http://localhost/api/v1?data=data')
         url.searchParams.append('data', JSON.stringify('__data__'))
@@ -29,9 +29,9 @@ describe('standardOpenAPICodec', () => {
           body: vi.fn(),
           headers: {},
           signal: undefined,
-        }, undefined, ping)
+        }, { name: 'John Doe' }, ping)
 
-        expect(input).toEqual('__deserialized__')
+        expect(input).toEqual({ name: 'John Doe' })
 
         expect(serializer.deserialize).toHaveBeenCalledOnce()
         expect(serializer.deserialize).toHaveBeenCalledWith(url.searchParams)
@@ -55,6 +55,25 @@ describe('standardOpenAPICodec', () => {
         expect(serializer.deserialize).toHaveBeenCalledOnce()
         expect(serializer.deserialize).toHaveBeenCalledWith(serialized)
       })
+
+      it('params and body are merged', async () => {
+        const serialized = '__data__'
+
+        serializer.deserialize.mockReturnValueOnce({ v1: 'v1' })
+
+        const input = await codec.decode({
+          method: 'POST',
+          url: new URL('http://localhost/api/v1?data=data'),
+          body: vi.fn(async () => serialized),
+          headers: {},
+          signal: undefined,
+        }, { v2: 'v2' }, ping)
+
+        expect(input).toEqual({ v1: 'v1', v2: 'v2' })
+
+        expect(serializer.deserialize).toHaveBeenCalledOnce()
+        expect(serializer.deserialize).toHaveBeenCalledWith(serialized)
+      })
     })
 
     describe('with detailed structure', () => {
@@ -124,6 +143,26 @@ describe('standardOpenAPICodec', () => {
         expect(serializer.deserialize).toHaveBeenNthCalledWith(1, serialized)
         expect(serializer.deserialize).toHaveBeenNthCalledWith(2, url.searchParams)
       })
+
+      it('can set query', async () => {
+        const serialized = '__data__'
+
+        serializer.deserialize.mockReturnValue('__deserialized__')
+        const url = new URL('http://localhost/api/v1?data=data')
+
+        const input = await codec.decode({
+          method: 'POST',
+          url,
+          body: vi.fn(async () => serialized),
+          headers: {
+            'content-type': 'application/json',
+          },
+          signal: undefined,
+        }, { name: 'John Doe' }, procedure) as any
+
+        input.query = { name: 'John Doe' }
+        expect(input.query).toEqual({ name: 'John Doe' })
+      })
     })
   })
 
@@ -152,10 +191,6 @@ describe('standardOpenAPICodec', () => {
         },
       })
 
-      it('throw on invalid output', async () => {
-        expect(() => codec.encode('__output__', procedure)).toThrowError()
-      })
-
       it('works', async () => {
         serializer.serialize.mockReturnValue('__serialized__')
 
@@ -175,15 +210,56 @@ describe('standardOpenAPICodec', () => {
           body: '__serialized__',
         })
 
+        expect(serializer.serialize).toHaveBeenCalledTimes(1)
+        expect(serializer.serialize).toHaveBeenCalledWith('__output__')
+      })
+
+      it('works with empty output', async () => {
+        serializer.serialize.mockReturnValue('__serialized__')
+
         expect(codec.encode({}, procedure)).toEqual({
           status: 298,
           headers: {},
           body: '__serialized__',
         })
 
-        expect(serializer.serialize).toHaveBeenCalledTimes(2)
-        expect(serializer.serialize).toHaveBeenNthCalledWith(1, '__output__')
-        expect(serializer.serialize).toHaveBeenNthCalledWith(2, undefined)
+        expect(serializer.serialize).toHaveBeenCalledTimes(1)
+        expect(serializer.serialize).toHaveBeenCalledWith(undefined)
+      })
+
+      it('works with custom status', async () => {
+        serializer.serialize.mockReturnValue('__serialized__')
+
+        const output = {
+          status: 201,
+          body: '__output__',
+          headers: {
+            'x-custom-header': 'custom-value',
+          },
+        }
+        const response = codec.encode(output, procedure)
+
+        expect(response).toEqual({
+          status: 201,
+          headers: {
+            'x-custom-header': 'custom-value',
+          },
+          body: '__serialized__',
+        })
+
+        expect(serializer.serialize).toHaveBeenCalledTimes(1)
+        expect(serializer.serialize).toHaveBeenCalledWith('__output__')
+      })
+
+      it.each([
+        'invalid',
+        { status: 'invalid' },
+        { status: 400 },
+        { status: 200.1 },
+        { status: 'invalid' },
+        { headers: 'invalid' },
+      ])('throw on invalid output: %s', async (output) => {
+        expect(() => codec.encode(output, procedure)).toThrowError()
       })
     })
   })

packages/openapi/src/adapters/standard/openapi-codec.ts

@@ -3,8 +3,9 @@ import type { StandardOpenAPISerializer } from '@orpc/openapi-client/standard'
 import type { AnyProcedure } from '@orpc/server'
 import type { StandardCodec, StandardParams } from '@orpc/server/standard'
 import type { StandardHeaders, StandardLazyRequest, StandardResponse } from '@orpc/standard-server'
+import { isORPCErrorStatus } from '@orpc/client'
 import { fallbackContractConfig } from '@orpc/contract'
-import { isObject } from '@orpc/shared'
+import { isObject, stringifyJSON } from '@orpc/shared'
 
 export class StandardOpenAPICodec implements StandardCodec {
   constructor(
@@ -65,15 +66,23 @@ export class StandardOpenAPICodec implements StandardCodec {
       }
     }
 
-    if (!isObject(output)) {
-      throw new Error(
-        'Invalid output structure for "detailed" output. Expected format: { body: any, headers?: Record<string, string | string[] | undefined> }',
-      )
+    if (!this.#isDetailedOutput(output)) {
+      throw new Error(`
+        Invalid "detailed" output structure:
+        • Expected an object with optional properties:
+          - status (number 200-399)
+          - headers (Record<string, string | string[]>)
+          - body (any)
+        • No extra keys allowed.
+
+        Actual value:
+          ${stringifyJSON(output)}
+      `)
     }
 
     return {
-      status: successStatus,
-      headers: output.headers as StandardHeaders ?? {},
+      status: output.status ?? successStatus,
+      headers: output.headers ?? {},
       body: this.serializer.serialize(output.body),
     }
   }
@@ -85,4 +94,20 @@ export class StandardOpenAPICodec implements StandardCodec {
       body: this.serializer.serialize(error.toJSON(), { outputFormat: 'plain' }),
     }
   }
+
+  #isDetailedOutput(output: unknown): output is { status?: number, body?: unknown, headers?: StandardHeaders } {
+    if (!isObject(output)) {
+      return false
+    }
+
+    if (output.headers && !isObject(output.headers)) {
+      return false
+    }
+
+    if (output.status !== undefined && (typeof output.status !== 'number' || !Number.isInteger(output.status) || isORPCErrorStatus(output.status))) {
+      return false
+    }
+
+    return true
+  }
 }