@orpc/openapi 0.0.0-unsafe-pr-2-20241118033608

package/src/generator.ts

@@ -0,0 +1,267 @@
+import { type ContractRouter, eachContractRouterLeaf } from '@orpc/contract'
+import { type Router, toContractRouter } from '@orpc/server'
+import { findDeepMatches, omit } from '@orpc/shared'
+import { preSerialize } from '@orpc/transformer'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import {
+  type MediaTypeObject,
+  type OpenAPIObject,
+  OpenApiBuilder,
+  type OperationObject,
+  type ParameterObject,
+  type RequestBodyObject,
+  type ResponseObject,
+} from 'openapi3-ts/oas31'
+import { extractJSONSchema, zodToJsonSchema } from './zod-to-json-schema'
+
+// Reference: https://spec.openapis.org/oas/v3.1.0.html#style-values
+
+export interface GenerateOpenAPIOptions {
+  /**
+   * Throw error when you missing define tag definition on OpenAPI root tags
+   *
+   * Example: if procedure has tags ['foo', 'bar'], and OpenAPI root tags is ['foo'], then error will be thrown
+   * Because OpenAPI root tags is missing 'bar' tag
+   *
+   * @default false
+   */
+  throwOnMissingTagDefinition?: boolean
+
+  /**
+   * Weather ignore procedures that has no path defined.
+   *
+   * @default false
+   */
+  ignoreUndefinedPathProcedures?: boolean
+}
+
+export function generateOpenAPI(
+  opts: {
+    router: ContractRouter | Router<any>
+  } & Omit<OpenAPIObject, 'openapi'>,
+  options?: GenerateOpenAPIOptions,
+): OpenAPIObject {
+  const throwOnMissingTagDefinition =
+    options?.throwOnMissingTagDefinition ?? false
+  const ignoreUndefinedPathProcedures =
+    options?.ignoreUndefinedPathProcedures ?? false
+
+  const builder = new OpenApiBuilder({
+    ...omit(opts, ['router']),
+    openapi: '3.1.0',
+  })
+
+  const rootTags = opts.tags?.map((tag) => tag.name) ?? []
+  const router = toContractRouter(opts.router)
+
+  eachContractRouterLeaf(router, (procedure, path_) => {
+    const internal = procedure.zz$cp
+
+    if (ignoreUndefinedPathProcedures && internal.path === undefined) {
+      return
+    }
+
+    const path = internal.path ?? `/${path_.map(encodeURIComponent).join('/')}`
+    const method = internal.method ?? 'POST'
+
+    const inputSchema = internal.InputSchema
+      ? zodToJsonSchema(internal.InputSchema, { mode: 'input' })
+      : {}
+    const outputSchema = internal.OutputSchema
+      ? zodToJsonSchema(internal.OutputSchema, { mode: 'output' })
+      : {}
+
+    const params: ParameterObject[] | undefined = (() => {
+      const names = path.match(/{([^}]+)}/g)
+
+      if (!names || !names.length) {
+        return undefined
+      }
+
+      if (typeof inputSchema !== 'object' || inputSchema.type !== 'object') {
+        throw new Error(
+          `When path has parameters, input schema must be an object [${path_.join('.')}]`,
+        )
+      }
+
+      return names
+        .map((raw) => raw.slice(1, -1))
+        .map((name) => {
+          const schema = inputSchema.properties?.[name]
+          const required = inputSchema.required?.includes(name)
+
+          if (!schema) {
+            throw new Error(
+              `Parameter ${name} is missing in input schema [${path_.join('.')}]`,
+            )
+          }
+
+          if (!required) {
+            throw new Error(
+              `Parameter ${name} must be required in input schema [${path_.join('.')}]`,
+            )
+          }
+
+          return {
+            name,
+            in: 'path',
+            required: true,
+            schema: schema as any,
+            example: internal.inputExample?.[name],
+          }
+        })
+    })()
+
+    const query: ParameterObject[] | undefined = (() => {
+      if (method !== 'GET' || Object.keys(inputSchema).length === 0) {
+        return undefined
+      }
+
+      if (typeof inputSchema !== 'object' || inputSchema.type !== 'object') {
+        throw new Error(
+          `When method is GET, input schema must be an object [${path_.join('.')}]`,
+        )
+      }
+
+      return Object.entries(inputSchema.properties ?? {})
+        .filter(([name]) => !params?.find((param) => param.name === name))
+        .map(([name, schema]) => {
+          return {
+            name,
+            in: 'query',
+            style: 'deepObject',
+            required: true,
+            schema: schema as any,
+            example: internal.inputExample?.[name],
+          }
+        })
+    })()
+
+    const parameters = [...(params ?? []), ...(query ?? [])]
+
+    const requestBody: RequestBodyObject | undefined = (() => {
+      if (method === 'GET') {
+        return undefined
+      }
+
+      const { schema, matches } = extractJSONSchema(inputSchema, isFileSchema)
+
+      const files = matches as (JSONSchema & {
+        type: 'string'
+        contentMediaType: string
+      })[]
+
+      const isStillHasFileSchema =
+        findDeepMatches(isFileSchema, schema).values.length > 0
+
+      if (files.length) {
+        parameters.push({
+          name: 'content-disposition',
+          in: 'header',
+          required: schema === undefined,
+          schema: {
+            type: 'string',
+            pattern: 'filename',
+            example: 'filename="file.png"',
+            description:
+              'To define the file name. Required when the request body is a file.',
+          },
+        })
+      }
+
+      const content: Record<string, MediaTypeObject> = {}
+
+      for (const file of files) {
+        content[file.contentMediaType] = {
+          schema: file as any,
+        }
+      }
+
+      if (schema !== undefined) {
+        content[
+          isStillHasFileSchema ? 'multipart/form-data' : 'application/json'
+        ] = {
+          schema: schema as any,
+          example: internal.inputExample,
+        }
+      }
+
+      return {
+        required: Boolean(internal.InputSchema?.isOptional()),
+        content,
+      }
+    })()
+
+    const successResponse: ResponseObject = (() => {
+      const { schema, matches } = extractJSONSchema(outputSchema, isFileSchema)
+      const files = matches as (JSONSchema & {
+        type: 'string'
+        contentMediaType: string
+      })[]
+
+      const isStillHasFileSchema =
+        findDeepMatches(isFileSchema, schema).values.length > 0
+
+      const content: Record<string, MediaTypeObject> = {}
+
+      for (const file of files) {
+        content[file.contentMediaType] = {
+          schema: file as any,
+        }
+      }
+
+      if (schema !== undefined) {
+        content[
+          isStillHasFileSchema ? 'multipart/form-data' : 'application/json'
+        ] = {
+          schema: schema as any,
+          example: internal.outputExample,
+        }
+      }
+
+      return {
+        description: 'OK',
+        content,
+      }
+    })()
+
+    if (throwOnMissingTagDefinition && internal.tags) {
+      const missingTag = internal.tags.find((tag) => !rootTags.includes(tag))
+
+      if (missingTag !== undefined) {
+        throw new Error(
+          `Tag "${missingTag}" is missing definition. Please define it in OpenAPI root tags object. [${path_.join('.')}]`,
+        )
+      }
+    }
+
+    const operation: OperationObject = {
+      summary: internal.summary,
+      description: internal.description,
+      deprecated: internal.deprecated,
+      tags: internal.tags,
+      operationId: path_.join('.'),
+      parameters: parameters.length ? parameters : undefined,
+      requestBody,
+      responses: {
+        '200': successResponse,
+      },
+    }
+
+    builder.addPath(path, {
+      [method.toLocaleLowerCase()]: operation,
+    })
+  })
+
+  return preSerialize(builder.getSpec()) as OpenAPIObject
+}
+
+function isFileSchema(schema: unknown) {
+  if (typeof schema !== 'object' || schema === null) return false
+  return (
+    'type' in schema &&
+    'contentMediaType' in schema &&
+    typeof schema.type === 'string' &&
+    typeof schema.contentMediaType === 'string'
+  )
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+/** unnoq */
+
+export * from './generator'

package/src/zod-to-json-schema.test.ts

@@ -0,0 +1,391 @@
+import { oz } from '@orpc/zod'
+import { Format } from 'json-schema-typed/draft-2020-12'
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { zodToJsonSchema } from './zod-to-json-schema'
+
+describe('primitive types', () => {
+  it('should convert string schema', () => {
+    const schema = z.string()
+    expect(zodToJsonSchema(schema)).toEqual({ type: 'string' })
+  })
+
+  it('should convert string schema with constraints', () => {
+    const schema = z
+      .string()
+      .min(5)
+      .max(10)
+      .email()
+      .regex(/^[a-z]+$/)
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'string',
+      minLength: 5,
+      maxLength: 10,
+      format: Format.Email,
+      pattern: '^[a-z]+$',
+    })
+  })
+
+  it('should convert number schema', () => {
+    const schema = z.number()
+    expect(zodToJsonSchema(schema)).toEqual({ type: 'number' })
+  })
+
+  it('should convert number schema with constraints', () => {
+    const schema = z.number().int().min(0).max(100).multipleOf(5)
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'integer',
+      minimum: 0,
+      maximum: 100,
+      multipleOf: 5,
+    })
+  })
+
+  it('should convert boolean schema', () => {
+    const schema = z.boolean()
+    expect(zodToJsonSchema(schema)).toEqual({ type: 'boolean' })
+  })
+
+  it('should convert null schema', () => {
+    const schema = z.null()
+    expect(zodToJsonSchema(schema)).toEqual({ type: 'null' })
+  })
+
+  it('should convert undefined schema', () => {
+    const schema = z.undefined()
+    expect(zodToJsonSchema(schema)).toEqual({ const: 'undefined' })
+  })
+
+  it('should convert literal schema', () => {
+    const schema = z.literal('hello')
+    expect(zodToJsonSchema(schema)).toEqual({ const: 'hello' })
+  })
+})
+
+describe('array types', () => {
+  it('should convert array schema', () => {
+    const schema = z.array(z.string())
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'array',
+    })
+  })
+
+  it('should convert array schema with length constraints', () => {
+    const schema = z.array(z.string()).min(1).max(5)
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'array',
+      minItems: 1,
+      maxItems: 5,
+    })
+  })
+
+  it('should convert tuple schema', () => {
+    const schema = z.tuple([z.string(), z.number()])
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'array',
+      prefixItems: [{ type: 'string' }, { type: 'number' }],
+    })
+  })
+})
+
+describe('object types', () => {
+  it('should convert object schema', () => {
+    const schema = z.object({
+      name: z.string(),
+      age: z.number(),
+      email: z.string().email(),
+    })
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+        email: { type: 'string', format: Format.Email },
+      },
+      required: ['name', 'age', 'email'],
+    })
+  })
+
+  it('should handle optional properties', () => {
+    const schema = z.object({
+      name: z.string(),
+      age: z.number().optional(),
+    })
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+      },
+      required: ['name'],
+    })
+  })
+
+  it('should convert record schema', () => {
+    const schema = z.record(z.string(), z.number())
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'object',
+      additionalProperties: { type: 'number' },
+    })
+  })
+})
+
+describe('union and intersection types', () => {
+  it('should convert union schema', () => {
+    const schema = z.union([z.string(), z.number()])
+    expect(zodToJsonSchema(schema)).toEqual({
+      anyOf: [{ type: 'string' }, { type: 'number' }],
+    })
+  })
+
+  it('should convert discriminated union schema', () => {
+    const schema = z.discriminatedUnion('type', [
+      z.object({ type: z.literal('a'), value: z.string() }),
+      z.object({ type: z.literal('b'), value: z.number() }),
+    ])
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      anyOf: [
+        {
+          type: 'object',
+          properties: {
+            type: { const: 'a' },
+            value: { type: 'string' },
+          },
+          required: ['type', 'value'],
+        },
+        {
+          type: 'object',
+          properties: {
+            type: { const: 'b' },
+            value: { type: 'number' },
+          },
+          required: ['type', 'value'],
+        },
+      ],
+    })
+  })
+
+  it('should convert intersection schema', () => {
+    const schema = z.intersection(
+      z.object({ name: z.string() }),
+      z.object({ age: z.number() }),
+    )
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      allOf: [
+        {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        },
+        {
+          type: 'object',
+          properties: { age: { type: 'number' } },
+          required: ['age'],
+        },
+      ],
+    })
+  })
+})
+
+describe('modifiers', () => {
+  it('should convert optional schema', () => {
+    const schema = z.string().optional()
+    expect(zodToJsonSchema(schema)).toEqual({
+      anyOf: [{ const: 'undefined' }, { type: 'string' }],
+    })
+  })
+
+  it('should convert nullable schema', () => {
+    const schema = z.string().nullable()
+    expect(zodToJsonSchema(schema)).toEqual({
+      anyOf: [{ type: 'null' }, { type: 'string' }],
+    })
+  })
+
+  it('should convert readonly schema', () => {
+    const schema = z.string().readonly()
+    expect(zodToJsonSchema(schema)).toEqual({ type: 'string' })
+  })
+})
+
+describe('special types', () => {
+  it('should convert date schema', () => {
+    const schema = z.date()
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'string',
+      format: Format.Date,
+    })
+  })
+
+  it('should convert enum schema', () => {
+    const schema = z.enum(['A', 'B', 'C'])
+    expect(zodToJsonSchema(schema)).toEqual({
+      enum: ['A', 'B', 'C'],
+    })
+  })
+
+  it('should convert native enum schema', () => {
+    enum TestEnum {
+      A = 'A',
+      B = 'B',
+    }
+    const schema = z.nativeEnum(TestEnum)
+    expect(zodToJsonSchema(schema)).toEqual({
+      enum: ['A', 'B'],
+    })
+  })
+})
+
+describe('transform and effects', () => {
+  it('should handle transform effects based on mode', () => {
+    const schema = z.string().transform((val) => val.length)
+
+    expect(zodToJsonSchema(schema, { mode: 'input' })).toEqual({
+      type: 'string',
+    })
+
+    expect(zodToJsonSchema(schema, { mode: 'output' })).toEqual({})
+  })
+})
+
+describe('lazy types', () => {
+  it('should handle lazy types with depth limit', () => {
+    type Tree = {
+      value: string
+      children?: Tree[]
+    }
+
+    const treeSchema: z.ZodType<Tree> = z.lazy(() =>
+      z.object({
+        value: z.string(),
+        children: z.array(treeSchema).optional(),
+      }),
+    )
+
+    expect(zodToJsonSchema(treeSchema, { maxLazyDepth: 2 })).toEqual({
+      type: 'object',
+      properties: {
+        value: { type: 'string' },
+        children: {
+          type: 'array',
+        },
+      },
+      required: ['value'],
+    })
+  })
+})
+
+describe('with custom json schema', () => {
+  const schema = oz.openapi(z.object({}), {
+    examples: [{ a: '23' }],
+  })
+
+  const schema2 = oz.openapi(
+    z.object({}),
+    {
+      examples: [{ a: '23' }, { b: '23' }],
+    },
+    { mode: 'input' },
+  )
+
+  const schema3 = oz.openapi(
+    z.object({}),
+    {
+      examples: [{ a: '23' }, { b: '23' }],
+    },
+    { mode: 'output' },
+  )
+
+  it('works with input mode', () => {
+    expect(zodToJsonSchema(schema, { mode: 'input' })).toEqual({
+      type: 'object',
+      examples: [{ a: '23' }],
+    })
+
+    expect(zodToJsonSchema(schema2, { mode: 'input' })).toEqual({
+      type: 'object',
+      examples: [{ a: '23' }, { b: '23' }],
+    })
+
+    expect(zodToJsonSchema(schema3, { mode: 'input' })).toEqual({
+      type: 'object',
+    })
+  })
+
+  it('works with output mode', () => {
+    expect(zodToJsonSchema(schema, { mode: 'output' })).toEqual({
+      type: 'object',
+      examples: [{ a: '23' }],
+    })
+
+    expect(zodToJsonSchema(schema2, { mode: 'output' })).toEqual({
+      type: 'object',
+    })
+
+    expect(zodToJsonSchema(schema3, { mode: 'output' })).toEqual({
+      type: 'object',
+      examples: [{ a: '23' }, { b: '23' }],
+    })
+  })
+
+  it('works on complex schema', () => {
+    const schema = z.object({
+      nested: z.object({
+        union: oz.openapi(
+          z.union([
+            oz.openapi(z.string(), {
+              $comment: 'comment for string',
+            }),
+            z.object({
+              url: oz.openapi(oz.url(), {
+                $comment: 'comment for url',
+              }),
+            }),
+          ]),
+          {
+            $comment: 'comment for nested',
+          },
+        ),
+      }),
+    })
+
+    expect(zodToJsonSchema(schema)).toEqual({
+      type: 'object',
+      properties: {
+        nested: {
+          type: 'object',
+          properties: {
+            union: {
+              $comment: 'comment for nested',
+              anyOf: [
+                {
+                  type: 'string',
+                  $comment: 'comment for string',
+                },
+                {
+                  type: 'object',
+                  properties: {
+                    url: {
+                      type: 'string',
+                      format: Format.URI,
+                      $comment: 'comment for url',
+                    },
+                  },
+                  required: ['url'],
+                },
+              ],
+            },
+          },
+          required: ['union'],
+        },
+      },
+      required: ['nested'],
+    })
+  })
+})