fix(openapi): correct success response spec for optional body (#319)

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

## Summary by CodeRabbit

- **New Features**
- Introduced flexible API schema handling that supports optional fields
for richer, adaptable output responses.
- **Refactor**
- Enhanced the documentation generation process to accurately
distinguish between required and optional data.
- **Tests**
- Expanded test coverage to validate diverse response scenarios and
ensure robust schema validations.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

packages/openapi/src/openapi-generator.test.ts

@@ -504,12 +504,9 @@ const successResponseTests: TestCase[] = [
     contract: oc.route({ outputStructure: 'detailed' }).output(z.object({ headers: z.string() })),
     error: 'When output structure is "detailed", output schema must satisfy',
   },
-]
-
-const errorResponseTests: TestCase[] = [
   {
-    name: 'without errors',
-    contract: oc,
+    name: 'outputStructure=compact + output is optional',
+    contract: oc.route({ outputStructure: 'compact' }).output(z.object({ name: z.string() }).optional()),
     expected: {
       '/': {
         post: expect.objectContaining({
@@ -518,7 +515,20 @@ const errorResponseTests: TestCase[] = [
               description: 'OK',
               content: {
                 'application/json': {
-                  schema: {},
+                  schema: {
+                    anyOf: [
+                      {
+                        type: 'object',
+                        properties: {
+                          name: { type: 'string' },
+                        },
+                        required: ['name'],
+                      },
+                      {
+                        not: {},
+                      },
+                    ],
+                  },
                 },
               },
             },
@@ -527,6 +537,55 @@ const errorResponseTests: TestCase[] = [
       },
     },
   },
+  {
+    name: 'outputStructure=detailed + body is optional',
+    contract: oc.route({ outputStructure: 'detailed' }).output(z.object({ body: z.object({ name: z.string() }).optional() })),
+    expected: {
+      '/': {
+        post: expect.objectContaining({
+          responses: {
+            200: {
+              description: 'OK',
+              content: {
+                'application/json': {
+                  schema: {
+                    anyOf: [
+                      {
+                        type: 'object',
+                        properties: {
+                          name: { type: 'string' },
+                        },
+                        required: ['name'],
+                      },
+                      {
+                        not: {},
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        }),
+      },
+    },
+  },
+]
+
+const errorResponseTests: TestCase[] = [
+  {
+    name: 'without errors',
+    contract: oc,
+    expected: {
+      '/': {
+        post: expect.objectContaining({
+          responses: {
+            200: expect.objectContaining({}),
+          },
+        }),
+      },
+    },
+  },
   {
     name: 'with errors',
     contract: oc.errors({

packages/openapi/src/openapi-generator.ts

@@ -8,11 +8,11 @@ import { toHttpPath } from '@orpc/client/standard'
 import { fallbackContractConfig, getEventIteratorSchemaDetails } from '@orpc/contract'
 import { getDynamicParams, StandardOpenAPIJsonSerializer } from '@orpc/openapi-client/standard'
 import { resolveContractProcedures } from '@orpc/server'
-import { clone } from '@orpc/shared'
+import { clone, toArray } from '@orpc/shared'
 import { applyCustomOpenAPIOperation } from './openapi-custom'
 import { checkParamsSchema, toOpenAPIContent, toOpenAPIEventIteratorContent, toOpenAPIMethod, toOpenAPIParameters, toOpenAPIPath, toOpenAPISchema } from './openapi-utils'
 import { CompositeSchemaConverter, type ConditionalSchemaConverter, type SchemaConverter } from './schema-converter'
-import { isAnySchema, isObjectSchema, separateObjectSchema } from './schema-utils'
+import { applySchemaOptionality, isAnySchema, isObjectSchema, separateObjectSchema } from './schema-utils'
 
 class OpenAPIGeneratorError extends Error {}
 
@@ -26,7 +26,7 @@ export class OpenAPIGenerator {
 
   constructor(options: OpenAPIGeneratorOptions = {}) {
     this.serializer = new StandardOpenAPIJsonSerializer(options)
-    this.converter = new CompositeSchemaConverter(options.schemaConverters ?? [])
+    this.converter = new CompositeSchemaConverter(toArray(options.schemaConverters))
   }
 
   async generate(router: AnyContractRouter | AnyRouter, base: Omit<OpenAPI.Document, 'openapi'>): Promise<OpenAPI.Document> {
@@ -214,15 +214,15 @@ export class OpenAPIGenerator {
       return
     }
 
-    const [_, json] = this.converter.convert(outputSchema, { strategy: 'output' })
+    const [required, json] = this.converter.convert(outputSchema, { strategy: 'output' })
 
     ref.responses ??= {}
     ref.responses[status] = {
       description,
     }
 
     if (outputStructure === 'compact') {
-      ref.responses[status].content = toOpenAPIContent(json)
+      ref.responses[status].content = toOpenAPIContent(applySchemaOptionality(required, json))
 
       return
     }
@@ -251,7 +251,9 @@ export class OpenAPIGenerator {
     }
 
     if (json.properties?.body !== undefined) {
-      ref.responses[status].content = toOpenAPIContent(json.properties.body)
+      ref.responses[status].content = toOpenAPIContent(
+        applySchemaOptionality(json.required?.includes('body') ?? false, json.properties.body),
+      )
     }
   }
 

packages/openapi/src/schema-utils.test.ts

@@ -1,6 +1,6 @@
 import type { JSONSchema, ObjectSchema } from './schema'
 import { isObject } from '@orpc/shared'
-import { filterSchemaBranches, isAnySchema, isFileSchema, isObjectSchema, separateObjectSchema } from './schema-utils'
+import { applySchemaOptionality, filterSchemaBranches, isAnySchema, isFileSchema, isObjectSchema, separateObjectSchema } from './schema-utils'
 
 it('isFileSchema', () => {
   expect(isFileSchema({ type: 'string', contentMediaType: 'image/png' })).toBe(true)
@@ -196,3 +196,9 @@ describe('filterSchemaBranches', () => {
     })
   })
 })
+
+it('applySchemaOptionality', () => {
+  expect(applySchemaOptionality(true, { type: 'string' })).toEqual({ type: 'string' })
+  expect(applySchemaOptionality(false, { type: 'string' })).toEqual({ anyOf: [{ type: 'string' }, { not: {} }] })
+  expect(applySchemaOptionality(false, true)).toEqual({ anyOf: [true, { not: {} }] })
+})

packages/openapi/src/schema-utils.ts

@@ -123,3 +123,16 @@ export function filterSchemaBranches(
 
   return [matches, schema]
 }
+
+export function applySchemaOptionality(required: boolean, schema: JSONSchema): JSONSchema {
+  if (required) {
+    return schema
+  }
+
+  return {
+    anyOf: [
+      schema,
+      { not: {} },
+    ],
+  }
+}