@trpc/openapi 11.15.1-alpha → 11.15.2-alpha

package/src/index.ts

@@ -1,2 +1,3 @@
 export { generateOpenAPIDocument } from './generate';
-export type { GenerateOptions, JsonSchema, OpenAPIDocument } from './generate';
+export type { GenerateOptions } from './generate';
+export * as OpenAPIV3_1 from './types';

package/src/schemaExtraction.ts

@@ -13,7 +13,7 @@ import type {
   $ZodTypeDef,
   GlobalMeta,
 } from 'zod/v4/core';
-import type { JsonSchema } from './generate';
+import type { SchemaObject } from './types';
 
 /** Description strings extracted from Zod `.describe()` calls, keyed by dot-delimited property path. */
 export interface DescriptionMap {
@@ -81,7 +81,6 @@ const wrapperDefTypes: ReadonlySet<$ZodTypeDef['type']> = new Set([
   'pipe',
   'transform',
   'promise',
-  'lazy',
 ]);
 
 /**
@@ -129,7 +128,7 @@ export function extractZodDescriptions(schema: unknown): DescriptionMap | null {
   }
 
   // Walk object shape
-  walkZodShape(schema, '', { registry, map });
+  walkZodShape(schema, '', { registry, map, seenLazy: new Set() });
   if (map.properties.size > 0) hasAny = true;
 
   return hasAny ? map : null;
@@ -138,9 +137,26 @@ export function extractZodDescriptions(schema: unknown): DescriptionMap | null {
 function walkZodShape(
   schema: $ZodType,
   prefix: string,
-  ctx: { registry: $ZodRegistry<GlobalMeta>; map: DescriptionMap },
+  ctx: {
+    registry: $ZodRegistry<GlobalMeta>;
+    map: DescriptionMap;
+    seenLazy: Set<$ZodType>;
+  },
 ): void {
   const unwrapped = unwrapZodSchema(schema);
+  const def = unwrapped._zod.def;
+
+  if (def.type === 'lazy' && 'getter' in def) {
+    if (ctx.seenLazy.has(unwrapped)) {
+      return;
+    }
+    ctx.seenLazy.add(unwrapped);
+    const inner = (def as { getter: () => unknown }).getter();
+    if (isZodSchema(inner)) {
+      walkZodShape(inner, prefix, ctx);
+    }
+    return;
+  }
 
   // If this is an array, check for a description on the element schema itself
   // (stored as `[]` in the path) and recurse into the element's shape.
@@ -325,23 +341,75 @@ function isProcedure(
  * JSON schema produced by the TypeScript type checker.  Mutates in place.
  */
 export function applyDescriptions(
-  schema: JsonSchema,
+  schema: SchemaObject,
   descs: DescriptionMap,
+  schemas?: Record<string, SchemaObject>,
 ): void {
   if (descs.self) {
     schema.description = descs.self;
   }
 
   for (const [propPath, description] of descs.properties) {
-    setNestedDescription(schema, propPath.split('.'), description);
+    setNestedDescription({
+      schema,
+      pathParts: propPath.split('.'),
+      description,
+      schemas,
+    });
   }
 }
 
-function setNestedDescription(
-  schema: JsonSchema,
-  pathParts: string[],
-  description: string,
-): void {
+function resolveSchemaRef(
+  schema: SchemaObject,
+  schemas?: Record<string, SchemaObject>,
+): SchemaObject | null {
+  const ref = schema.$ref;
+  if (!ref) {
+    return schema;
+  }
+  if (!schemas || !ref.startsWith('#/components/schemas/')) {
+    return null;
+  }
+
+  const refName = ref.slice('#/components/schemas/'.length);
+  return refName ? (schemas[refName] ?? null) : null;
+}
+
+function getArrayItemsSchema(schema: SchemaObject): SchemaObject | null {
+  const items = schema.items;
+  if (schema.type !== 'array' || items == null || items === false) {
+    return null;
+  }
+  return items;
+}
+
+function getPropertySchema(
+  schema: SchemaObject,
+  propertyName: string,
+): SchemaObject | null {
+  return schema.properties?.[propertyName] ?? null;
+}
+
+function setLeafDescription(schema: SchemaObject, description: string): void {
+  if (schema.$ref) {
+    const ref = schema.$ref;
+    delete schema.$ref;
+    schema.allOf = [{ $ref: ref }, ...(schema.allOf ?? [])];
+  }
+  schema.description = description;
+}
+
+function setNestedDescription({
+  schema,
+  pathParts,
+  description,
+  schemas,
+}: {
+  schema: SchemaObject;
+  pathParts: string[];
+  description: string;
+  schemas?: Record<string, SchemaObject>;
+}): void {
   if (pathParts.length === 0) return;
 
   const [head, ...rest] = pathParts;
@@ -349,35 +417,37 @@ function setNestedDescription(
 
   // `[]` means "array items" — navigate to the `items` sub-schema
   if (head === '[]') {
-    const items =
-      schema.type === 'array' &&
-      schema.items &&
-      typeof schema.items === 'object'
-        ? schema.items
-        : null;
+    const items = getArrayItemsSchema(schema);
     if (!items) return;
     if (rest.length === 0) {
-      items.description = description;
+      setLeafDescription(items, description);
     } else {
-      setNestedDescription(items, rest, description);
+      const target = resolveSchemaRef(items, schemas) ?? items;
+      setNestedDescription({
+        schema: target,
+        pathParts: rest,
+        description,
+        schemas,
+      });
     }
     return;
   }
 
-  const propSchema = schema.properties?.[head];
-  if (!propSchema || typeof propSchema !== 'object') return;
+  const propSchema = getPropertySchema(schema, head);
+  if (!propSchema) return;
 
   if (rest.length === 0) {
     // Leaf — Zod .describe() takes priority over JSDoc
-    propSchema.description = description;
+    setLeafDescription(propSchema, description);
   } else {
     // For arrays, step through `items` transparently
-    const target =
-      propSchema.type === 'array' &&
-      propSchema.items &&
-      typeof propSchema.items === 'object'
-        ? propSchema.items
-        : propSchema;
-    setNestedDescription(target, rest, description);
+    const target = getArrayItemsSchema(propSchema) ?? propSchema;
+    const resolvedTarget = resolveSchemaRef(target, schemas) ?? target;
+    setNestedDescription({
+      schema: resolvedTarget,
+      pathParts: rest,
+      description,
+      schemas,
+    });
   }
 }

package/src/types.ts

@@ -0,0 +1,151 @@
+import type { OpenAPIV3_1 as BaseOpenAPIV3_1 } from 'openapi-types';
+
+export type Replace<TTarget, TReplaceWith> = Omit<TTarget, keyof TReplaceWith> &
+  TReplaceWith;
+
+export type SchemaType =
+  | 'array'
+  | 'boolean'
+  | 'integer'
+  | 'null'
+  | 'number'
+  | 'object'
+  | 'string';
+
+export type PrimitiveSchemaType = SchemaType;
+
+export type HttpMethods = BaseOpenAPIV3_1.HttpMethods;
+export type ReferenceObject = BaseOpenAPIV3_1.ReferenceObject;
+export type ExampleObject = BaseOpenAPIV3_1.ExampleObject;
+export type DiscriminatorObject = BaseOpenAPIV3_1.DiscriminatorObject;
+export type ExternalDocumentationObject =
+  BaseOpenAPIV3_1.ExternalDocumentationObject;
+export type XMLObject = BaseOpenAPIV3_1.XMLObject;
+export type LinkObject = BaseOpenAPIV3_1.LinkObject;
+export type SecuritySchemeObject = BaseOpenAPIV3_1.SecuritySchemeObject;
+
+export type SchemaObject = Replace<
+  BaseOpenAPIV3_1.BaseSchemaObject,
+  {
+    $ref?: string;
+    $defs?: Record<string, SchemaObject>;
+    $schema?: string;
+    type?: string | string[];
+    properties?: Record<string, SchemaObject>;
+    required?: string[];
+    items?: SchemaObject | false;
+    prefixItems?: SchemaObject[];
+    const?: string | number | boolean | null;
+    enum?: (string | number | boolean | null)[];
+    oneOf?: SchemaObject[];
+    anyOf?: SchemaObject[];
+    allOf?: SchemaObject[];
+    not?: SchemaObject;
+    additionalProperties?: boolean | SchemaObject;
+    discriminator?: DiscriminatorObject;
+    externalDocs?: ExternalDocumentationObject;
+    xml?: XMLObject;
+    contentMediaType?: string;
+    exclusiveMinimum?: boolean | number;
+    exclusiveMaximum?: boolean | number;
+  }
+>;
+
+export type SchemaLike = SchemaObject;
+
+export interface ArraySchemaObject extends SchemaObject {
+  type: 'array';
+  items: SchemaObject | false;
+}
+
+export type MediaTypeObject = Replace<
+  BaseOpenAPIV3_1.MediaTypeObject,
+  {
+    schema?: SchemaObject | ReferenceObject;
+    examples?: Record<string, ReferenceObject | ExampleObject>;
+  }
+>;
+
+export interface ParameterBaseObject
+  extends Replace<
+    BaseOpenAPIV3_1.ParameterBaseObject,
+    {
+      schema?: SchemaObject | ReferenceObject;
+      examples?: Record<string, ReferenceObject | ExampleObject>;
+      content?: Record<string, MediaTypeObject>;
+    }
+  > {}
+
+export interface ParameterObject extends ParameterBaseObject {
+  name: string;
+  in: string;
+}
+
+export type HeaderObject = ParameterBaseObject;
+
+export type RequestBodyObject = Replace<
+  BaseOpenAPIV3_1.RequestBodyObject,
+  {
+    content: Record<string, MediaTypeObject>;
+  }
+>;
+
+export type ResponseObject = Replace<
+  BaseOpenAPIV3_1.ResponseObject,
+  {
+    headers?: Record<string, ReferenceObject | HeaderObject>;
+    content?: Record<string, MediaTypeObject>;
+    links?: Record<string, ReferenceObject | LinkObject>;
+  }
+>;
+
+export type ResponsesObject = Record<string, ReferenceObject | ResponseObject>;
+
+export type OperationObject<T extends {} = {}> = Replace<
+  BaseOpenAPIV3_1.OperationObject<T>,
+  {
+    parameters?: (ReferenceObject | ParameterObject)[];
+    requestBody?: ReferenceObject | RequestBodyObject;
+    responses?: ResponsesObject;
+    callbacks?: Record<string, ReferenceObject | CallbackObject>;
+  }
+> &
+  T;
+
+export type PathItemObject<T extends {} = {}> = Replace<
+  BaseOpenAPIV3_1.PathItemObject<T>,
+  {
+    parameters?: (ReferenceObject | ParameterObject)[];
+  }
+> & {
+  [method in HttpMethods]?: OperationObject<T>;
+};
+
+export type PathsObject<T extends {} = {}, TPath extends {} = {}> = Record<
+  string,
+  (PathItemObject<T> & TPath) | undefined
+>;
+
+export type CallbackObject = Record<string, PathItemObject | ReferenceObject>;
+
+export type ComponentsObject = Replace<
+  BaseOpenAPIV3_1.ComponentsObject,
+  {
+    schemas?: Record<string, SchemaObject>;
+    responses?: Record<string, ReferenceObject | ResponseObject>;
+    parameters?: Record<string, ReferenceObject | ParameterObject>;
+    requestBodies?: Record<string, ReferenceObject | RequestBodyObject>;
+    headers?: Record<string, ReferenceObject | HeaderObject>;
+    links?: Record<string, ReferenceObject | LinkObject>;
+    callbacks?: Record<string, ReferenceObject | CallbackObject>;
+    pathItems?: Record<string, ReferenceObject | PathItemObject>;
+  }
+>;
+
+export type Document<T extends {} = {}> = Replace<
+  BaseOpenAPIV3_1.Document<T>,
+  {
+    paths?: PathsObject<T>;
+    components?: ComponentsObject;
+  }
+>;