feat(openapi): async json schema converter support (#407)

This will expend the supports of converter for dynamic cases, or lazy
cases

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

## Summary by CodeRabbit

- **Documentation**
- Added a new section in the OpenAPI specification providing guidance on
extending JSON schema conversion using custom converters.

- **New Features / Refactor**
- Improved asynchronous processing for API generation and schema
conversion, ensuring smoother and more reliable handling of contract
procedures.

- **Tests**
- Updated test scenarios to validate asynchronous behavior, reinforcing
the stability of the new improvements.

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

Author: unnoq

apps/content/docs/openapi/openapi-specification.md

@@ -41,6 +41,31 @@ oRPC supports OpenAPI 3.1.1 and integrates seamlessly with popular schema librar
 Interested in support for additional schema libraries? [Let us know](https://github.com/unnoq/orpc/discussions/categories/ideas)!
 :::
 
+::: details Want to create your own JSON schema converter?
+You can use any existing `X to JSON Schema` converter to add support for additional schema libraries. For example, if you want to use [Valibot](https://valibot.dev) with oRPC (if not supported), you can create a custom converter to convert Valibot schemas into JSON Schema.
+
+```ts
+import type { AnySchema } from '@orpc/contract'
+import type { ConditionalSchemaConverter, JSONSchema, SchemaConvertOptions } from '@orpc/openapi'
+import type { ConversionConfig } from '@valibot/to-json-schema'
+import { toJsonSchema } from '@valibot/to-json-schema'
+
+export class ValibotToJsonSchemaConverter implements ConditionalSchemaConverter {
+  condition(schema: AnySchema | undefined): boolean {
+    return schema !== undefined && schema['~standard'].vendor === 'valibot'
+  }
+
+  convert(schema: AnySchema | undefined, _options: SchemaConvertOptions): [required: boolean, jsonSchema: Exclude<JSONSchema, boolean>] {
+    // Most JSON schema converters do not convert the `required` property separately, so returning `true` is acceptable here.
+    return [true, toJsonSchema(schema as any)]
+  }
+}
+```
+
+:::info
+It's recommended to use the built-in converters because the oRPC implementations handle many edge cases and supports every type that oRPC offers.
+:::
+
 ```ts twoslash
 import { contract, router } from './shared/planet'
 // ---cut---

packages/openapi/src/openapi-generator.ts

@@ -34,9 +34,15 @@ export class OpenAPIGenerator {
     const doc: OpenAPI.Document = clone(base) as OpenAPI.Document
     doc.openapi = '3.1.1'
 
-    const errors: string[] = []
+    const contracts: { contract: AnyContractProcedure, path: readonly string[] }[] = []
 
     await resolveContractProcedures({ path: [], router }, ({ contract, path }) => {
+      contracts.push({ contract, path })
+    })
+
+    const errors: string[] = []
+
+    for (const { contract, path } of contracts) {
       const operationId = path.join('.')
 
       try {
@@ -53,9 +59,9 @@ export class OpenAPIGenerator {
           tags: def.route.tags?.map(tag => tag),
         }
 
-        this.#request(operationObjectRef, def)
-        this.#successResponse(operationObjectRef, def)
-        this.#errorResponse(operationObjectRef, def)
+        await this.#request(operationObjectRef, def)
+        await this.#successResponse(operationObjectRef, def)
+        await this.#errorResponse(operationObjectRef, def)
 
         doc.paths ??= {}
         doc.paths[httpPath] ??= {}
@@ -70,7 +76,7 @@ export class OpenAPIGenerator {
           `[OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: ${operationId}\n${e.message}`,
         )
       }
-    })
+    }
 
     if (errors.length) {
       throw new OpenAPIGeneratorError(
@@ -81,16 +87,16 @@ export class OpenAPIGenerator {
     return this.serializer.serialize(doc)[0] as OpenAPI.Document
   }
 
-  #request(ref: OpenAPI.OperationObject, def: AnyContractProcedure['~orpc']): void {
+  async #request(ref: OpenAPI.OperationObject, def: AnyContractProcedure['~orpc']): Promise<void> {
     const method = fallbackContractConfig('defaultMethod', def.route.method)
     const details = getEventIteratorSchemaDetails(def.inputSchema)
 
     if (details) {
       ref.requestBody = {
         required: true,
         content: toOpenAPIEventIteratorContent(
-          this.converter.convert(details.yields, { strategy: 'input' }),
-          this.converter.convert(details.returns, { strategy: 'input' }),
+          await this.converter.convert(details.yields, { strategy: 'input' }),
+          await this.converter.convert(details.returns, { strategy: 'input' }),
         ),
       }
 
@@ -99,7 +105,7 @@ export class OpenAPIGenerator {
 
     const dynamicParams = getDynamicParams(def.route.path)?.map(v => v.name)
     const inputStructure = fallbackContractConfig('defaultInputStructure', def.route.inputStructure)
-    let [required, schema] = this.converter.convert(def.inputSchema, { strategy: 'input' })
+    let [required, schema] = await this.converter.convert(def.inputSchema, { strategy: 'input' })
 
     if (isAnySchema(schema) && !dynamicParams?.length) {
       return
@@ -195,7 +201,7 @@ export class OpenAPIGenerator {
     }
   }
 
-  #successResponse(ref: OpenAPI.OperationObject, def: AnyContractProcedure['~orpc']): void {
+  async #successResponse(ref: OpenAPI.OperationObject, def: AnyContractProcedure['~orpc']): Promise<void> {
     const outputSchema = def.outputSchema
     const status = fallbackContractConfig('defaultSuccessStatus', def.route.successStatus)
     const description = fallbackContractConfig('defaultSuccessDescription', def.route?.successDescription)
@@ -207,15 +213,15 @@ export class OpenAPIGenerator {
       ref.responses[status] = {
         description,
         content: toOpenAPIEventIteratorContent(
-          this.converter.convert(eventIteratorSchemaDetails.yields, { strategy: 'output' }),
-          this.converter.convert(eventIteratorSchemaDetails.returns, { strategy: 'output' }),
+          await this.converter.convert(eventIteratorSchemaDetails.yields, { strategy: 'output' }),
+          await this.converter.convert(eventIteratorSchemaDetails.returns, { strategy: 'output' }),
         ),
       }
 
       return
     }
 
-    const [required, json] = this.converter.convert(outputSchema, { strategy: 'output' })
+    const [required, json] = await this.converter.convert(outputSchema, { strategy: 'output' })
 
     ref.responses ??= {}
     ref.responses[status] = {
@@ -258,7 +264,7 @@ export class OpenAPIGenerator {
     }
   }
 
-  #errorResponse(ref: OpenAPI.OperationObject, def: AnyContractProcedure['~orpc']): void {
+  async #errorResponse(ref: OpenAPI.OperationObject, def: AnyContractProcedure['~orpc']): Promise<void> {
     const errorMap = def.errorMap as ErrorMap
 
     const errors: Record<string, JSONSchema[]> = {}
@@ -273,7 +279,7 @@ export class OpenAPIGenerator {
       const status = fallbackORPCErrorStatus(code, config.status)
       const message = fallbackORPCErrorMessage(code, config.message)
 
-      const [dataRequired, dataSchema] = this.converter.convert(config.data, { strategy: 'output' })
+      const [dataRequired, dataSchema] = await this.converter.convert(config.data, { strategy: 'output' })
 
       errors[status] ??= []
       errors[status].push({

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

@@ -23,8 +23,8 @@ describe('compositeSchemaConverter', () => {
 
   const schema = z.object({})
 
-  it('fallback to any if no condition is matched', () => {
-    expect(converter.convert(schema, { strategy: 'input' })).toEqual([false, {}])
+  it('fallback to any if no condition is matched', async () => {
+    await expect(converter.convert(schema, { strategy: 'input' })).resolves.toEqual([false, {}])
 
     expect(converter1.condition).toBeCalledTimes(1)
     expect(converter1.condition).toBeCalledWith(schema, { strategy: 'input' })
@@ -34,11 +34,11 @@ describe('compositeSchemaConverter', () => {
     expect(converter2.convert).not.toHaveBeenCalled()
   })
 
-  it('return result of first converter if condition is matched', () => {
+  it('return result of first converter if condition is matched', async () => {
     converter1.condition.mockReturnValue(true)
     converter1.convert.mockReturnValue('__MATCHED__')
 
-    expect(converter.convert(schema, { strategy: 'input' })).toEqual('__MATCHED__')
+    await expect(converter.convert(schema, { strategy: 'input' })).resolves.toEqual('__MATCHED__')
 
     expect(converter1.condition).toBeCalledTimes(1)
     expect(converter1.convert).toHaveBeenCalled()

packages/openapi/src/schema-converter.ts

@@ -1,16 +1,17 @@
 import type { AnySchema } from '@orpc/contract'
+import type { Promisable } from '@orpc/shared'
 import type { JSONSchema } from './schema'
 
 export interface SchemaConvertOptions {
   strategy: 'input' | 'output'
 }
 
 export interface SchemaConverter {
-  convert(schema: AnySchema | undefined, options: SchemaConvertOptions): [required: boolean, jsonSchema: JSONSchema]
+  convert(schema: AnySchema | undefined, options: SchemaConvertOptions): Promisable<[required: boolean, jsonSchema: JSONSchema]>
 }
 
 export interface ConditionalSchemaConverter extends SchemaConverter {
-  condition(schema: AnySchema | undefined, options: SchemaConvertOptions): boolean
+  condition(schema: AnySchema | undefined, options: SchemaConvertOptions): Promisable<boolean>
 }
 
 export class CompositeSchemaConverter implements SchemaConverter {
@@ -20,9 +21,9 @@ export class CompositeSchemaConverter implements SchemaConverter {
     this.converters = converters
   }
 
-  convert(schema: AnySchema | undefined, options: SchemaConvertOptions): [required: boolean, jsonSchema: JSONSchema] {
+  async convert(schema: AnySchema | undefined, options: SchemaConvertOptions): Promise<[required: boolean, jsonSchema: JSONSchema]> {
     for (const converter of this.converters) {
-      if (converter.condition(schema, options)) {
+      if (await converter.condition(schema, options)) {
         return converter.convert(schema, options)
       }
     }