zod-openapi 2.13.0 → 2.14.0

package/README.md

@@ -17,12 +17,14 @@ A Typescript library to use <a href="https://github.com/colinhacks/zod">Zod</a>
 
 ## Install
 
-Install via `npm` or `yarn`:
+Install via `npm`, `yarn` or `pnpm`:
 
 ```bash
 npm install zod zod-openapi
 ## or
 yarn add zod zod-openapi
+## or
+pnpm install zod zod-openapi
 ```
 
 ## Usage
@@ -48,8 +50,8 @@ Use the `.openapi()` method to add metadata to a specific Zod type. The `.openap
 | :-------------: | :-------------------------------------------------------------------------------------------------------------------------: |
 | OpenAPI Options | This will take any option you would put on a [SchemaObject](https://swagger.io/docs/specification/data-models/data-types/). |
 |  `effectType`   |                             Use to override the creation type for a [Zod Effect](#zod-effects)                              |
-|     `param`     |                                Use to provide metadata for [request parameters](#parameters)                                |
 |    `header`     |                              Use to provide metadata for [response headers](#response-headers)                              |
+|     `param`     |                                Use to provide metadata for [request parameters](#parameters)                                |
 |      `ref`      |                                 Use this to [auto register a schema](#creating-components)                                  |
 |    `refType`    |                 Use this to set the creation type for a component which is not referenced in the document.                  |
 |     `type`      |                 Use this to override the generated type. If this is provided no metadata will be generated.                 |
@@ -328,13 +330,13 @@ createDocument({
 
 ##### Zod Effects
 
-`.transform()` and `.pipe()` are complicated because they technically comprise of two types (input & output). This means that we need to understand which type you are creating. In particular with transform it is very difficult to infer the output type. This library will automatically select which _type_ to use by checking how the schema is used based on the following rules:
+`.transform()`, `.default()` and `.pipe()` are complicated because they technically comprise of two types (input & output). This means that we need to understand which type you are creating. In particular with transform it is very difficult to infer the output type. This library will automatically select which _type_ to use by checking how the schema is used based on the following rules:
 
 _Input_: Request Bodies, Request Parameters, Headers
 
 _Output_: Responses, Response Headers
 
-If a registered schema with a transform or pipeline is used in both a request and response schema you will receive an error because the created schema for each will be different. To override the creation type for a specific ZodEffect, add an `.openapi()` field on it and set the `effectType` field to `input`, `output` or `same`. This will force this library to always generate the input/output type even if we are creating a response (output) or request (input) type. You typically want to set this when you know the type has not changed in the transform. `same` is the recommended choice as it will throw a type error if the input and output types in the transform drift.
+If a registered schema with a transform or pipeline is used in both a request and response schema you will receive an error because the created schema for each will be different. To override the creation type for a specific ZodEffect, add an `.openapi()` field on it and set the `effectType` field to `input`, `output` or `same`. This will force this library to always generate the input/output type even if we are creating a response (output) or request (input) type. You typically want to set this when you know the type has not changed in the transform. `same` is the recommended choice as it will generate a TypeScript compiler error if the input and output types in the transform drift.
 
 `.preprocess()` will always return the `output` type even if we are creating an input schema. If a different input type is required you can achieve this with a `.transform()` combined with a `.pipe()` or simply declare a manual `type` in `.openapi()`.
 
@@ -578,27 +580,27 @@ See the library in use in the [examples](./examples/) folder.
 ### Prerequisites
 
 - Node.js LTS
-- Yarn 1.x
+- pnpm
 
 ```shell
-yarn
-yarn build
+pnpm
+pnpm build
 ```
 
 ### Test
 
 ```shell
-yarn test
+pnpm test
 ```
 
 ### Lint
 
 ```shell
 # Fix issues
-yarn format
+pnpm format
 
 # Check for issues
-yarn lint
+pnpm lint
 ```
 
 ### Release

package/lib-commonjs/index.js

@@ -178,11 +178,11 @@ var throwTransformError = (effect) => {
 
 This may cause the schema to render incorrectly and is most likely a mistake. You can resolve this by:
 
-1. Setting an \`effectType\` on the transformation to \`same\` or \`${opposite}\` eg. \`.openapi({type: 'same'})\`
+1. Setting an \`effectType\` on one of the transformations to \`same\` (Not applicable for ZodDefault), \`input\` or \`output\` eg. \`.openapi({type: 'same'})\`
 2. Wrapping the transformation in a ZodPipeline
 3. Assigning a manual type to the transformation eg. \`.openapi({type: 'string'})\`
 4. Removing the transformation
-5. Deregistering the component containing the transformation`
+5. Deregister the component containing the transformation`
   );
 };
 var resolveSingleEffect = (effect, state) => {
@@ -1442,11 +1442,12 @@ var createParamOrRef = (zodSchema, components, subpath, type, name) => {
   }
   return paramObject;
 };
-var createParameters = (type, zodObject, components, subpath) => {
-  if (!zodObject) {
+var createParameters = (type, zodObjectType, components, subpath) => {
+  if (!zodObjectType) {
     return [];
   }
-  return Object.entries(zodObject.shape).map(
+  const zodObject = getZodObject(zodObjectType, "input").shape;
+  return Object.entries(zodObject).map(
     ([key, zodSchema]) => createParamOrRef(zodSchema, components, [...subpath, key], type, key)
   );
 };
@@ -1500,6 +1501,27 @@ var createParametersObject = (parameters, requestParams, components, subpath) =>
   ];
   return combinedParameters.length ? combinedParameters : void 0;
 };
+var getZodObject = (schema, type) => {
+  if (isZodType(schema, "ZodObject")) {
+    return schema;
+  }
+  if (isZodType(schema, "ZodLazy")) {
+    return getZodObject(schema.schema, type);
+  }
+  if (isZodType(schema, "ZodEffects")) {
+    return getZodObject(schema.innerType(), type);
+  }
+  if (isZodType(schema, "ZodBranded")) {
+    return getZodObject(schema.unwrap(), type);
+  }
+  if (isZodType(schema, "ZodPipeline")) {
+    if (type === "input") {
+      return getZodObject(schema._def.in, type);
+    }
+    return getZodObject(schema._def.out, type);
+  }
+  throw new Error("failed to find ZodObject in schema");
+};
 
 // src/create/content.ts
 var createMediaTypeSchema = (schemaObject, components, type, subpath) => {

package/lib-esm/index.mjs

@@ -154,11 +154,11 @@ var throwTransformError = (effect) => {
 
 This may cause the schema to render incorrectly and is most likely a mistake. You can resolve this by:
 
-1. Setting an \`effectType\` on the transformation to \`same\` or \`${opposite}\` eg. \`.openapi({type: 'same'})\`
+1. Setting an \`effectType\` on one of the transformations to \`same\` (Not applicable for ZodDefault), \`input\` or \`output\` eg. \`.openapi({type: 'same'})\`
 2. Wrapping the transformation in a ZodPipeline
 3. Assigning a manual type to the transformation eg. \`.openapi({type: 'string'})\`
 4. Removing the transformation
-5. Deregistering the component containing the transformation`
+5. Deregister the component containing the transformation`
   );
 };
 var resolveSingleEffect = (effect, state) => {
@@ -1418,11 +1418,12 @@ var createParamOrRef = (zodSchema, components, subpath, type, name) => {
   }
   return paramObject;
 };
-var createParameters = (type, zodObject, components, subpath) => {
-  if (!zodObject) {
+var createParameters = (type, zodObjectType, components, subpath) => {
+  if (!zodObjectType) {
     return [];
   }
-  return Object.entries(zodObject.shape).map(
+  const zodObject = getZodObject(zodObjectType, "input").shape;
+  return Object.entries(zodObject).map(
     ([key, zodSchema]) => createParamOrRef(zodSchema, components, [...subpath, key], type, key)
   );
 };
@@ -1476,6 +1477,27 @@ var createParametersObject = (parameters, requestParams, components, subpath) =>
   ];
   return combinedParameters.length ? combinedParameters : void 0;
 };
+var getZodObject = (schema, type) => {
+  if (isZodType(schema, "ZodObject")) {
+    return schema;
+  }
+  if (isZodType(schema, "ZodLazy")) {
+    return getZodObject(schema.schema, type);
+  }
+  if (isZodType(schema, "ZodEffects")) {
+    return getZodObject(schema.innerType(), type);
+  }
+  if (isZodType(schema, "ZodBranded")) {
+    return getZodObject(schema.unwrap(), type);
+  }
+  if (isZodType(schema, "ZodPipeline")) {
+    if (type === "input") {
+      return getZodObject(schema._def.in, type);
+    }
+    return getZodObject(schema._def.out, type);
+  }
+  throw new Error("failed to find ZodObject in schema");
+};
 
 // src/create/content.ts
 var createMediaTypeSchema = (schemaObject, components, type, subpath) => {

package/lib-types/create/document.d.ts

@@ -1,4 +1,4 @@
-import type { AnyZodObject, ZodType } from 'zod';
+import type { AnyZodObject, ZodType, ZodTypeDef } from 'zod';
 import type { OpenApiVersion } from '../openapi';
 import type { oas30, oas31 } from '../openapi3-ts/dist';
 export interface ZodOpenApiMediaTypeObject extends Omit<oas31.MediaTypeObject & oas30.MediaTypeObject, 'schema'> {
@@ -24,7 +24,7 @@ export interface ZodOpenApiResponsesObject extends oas31.ISpecificationExtension
     [statuscode: `${1 | 2 | 3 | 4 | 5}${string}`]: ZodOpenApiResponseObject | oas31.ReferenceObject;
 }
 export type ZodOpenApiParameters = {
-    [type in oas31.ParameterLocation & oas30.ParameterLocation]?: AnyZodObject;
+    [type in oas31.ParameterLocation & oas30.ParameterLocation]?: ZodObjectInputType;
 };
 export interface ZodOpenApiOperationObject extends Omit<oas31.OperationObject & oas30.OperationObject, 'requestBody' | 'responses' | 'parameters'> {
     parameters?: Array<ZodType | oas31.ParameterObject | oas30.ParameterObject | oas31.ReferenceObject | oas30.ReferenceObject>;
@@ -59,4 +59,5 @@ export interface ZodOpenApiObject extends Omit<oas31.OpenAPIObject, 'openapi' |
     webhooks?: ZodOpenApiPathsObject;
     components?: ZodOpenApiComponentsObject;
 }
+export type ZodObjectInputType<Output = unknown, Def extends ZodTypeDef = ZodTypeDef, Input = Record<string, unknown>> = ZodType<Output, Def, Input>;
 export declare const createDocument: (zodOpenApiObject: ZodOpenApiObject) => oas31.OpenAPIObject;

package/lib-types/create/parameters.d.ts

@@ -1,9 +1,10 @@
-import type { ZodType } from 'zod';
+import type { AnyZodObject, ZodType } from 'zod';
 import type { oas30, oas31 } from '../openapi3-ts/dist';
 import type { ComponentsObject } from './components';
-import type { ZodOpenApiParameters } from './document';
+import type { ZodObjectInputType, ZodOpenApiParameters } from './document';
 export declare const createComponentParamRef: (ref: string) => string;
 export declare const createBaseParameter: (schema: ZodType, components: ComponentsObject, subpath: string[]) => oas31.BaseParameterObject;
 export declare const createParamOrRef: (zodSchema: ZodType, components: ComponentsObject, subpath: string[], type?: keyof ZodOpenApiParameters, name?: string) => oas31.ParameterObject | oas31.ReferenceObject;
 export declare const createManualParameters: (parameters: Array<oas31.ParameterObject | oas31.ReferenceObject | oas30.ParameterObject | oas30.ReferenceObject | ZodType> | undefined, components: ComponentsObject, subpath: string[]) => Array<oas31.ParameterObject | oas31.ReferenceObject>;
 export declare const createParametersObject: (parameters: Array<oas31.ParameterObject | oas31.ReferenceObject | oas30.ParameterObject | oas30.ReferenceObject | ZodType> | undefined, requestParams: ZodOpenApiParameters | undefined, components: ComponentsObject, subpath: string[]) => Array<oas31.ParameterObject | oas31.ReferenceObject> | undefined;
+export declare const getZodObject: (schema: ZodObjectInputType, type: 'input' | 'output') => AnyZodObject;

package/lib-types/extendZod.d.ts

@@ -2,51 +2,70 @@ import type { UnknownKeysParam, ZodDate, ZodObject, ZodRawShape, ZodTypeAny, z }
 import type { CreationType } from './create/components';
 import type { oas30, oas31 } from './openapi3-ts/dist';
 type SchemaObject = oas30.SchemaObject & oas31.SchemaObject;
+/**
+ * zod-openapi metadata
+ */
 interface ZodOpenApiMetadata<T extends ZodTypeAny, TInferred = z.input<T> | z.output<T>> extends SchemaObject {
     example?: TInferred;
     examples?: [TInferred, ...TInferred[]];
     default?: T extends ZodDate ? string : TInferred;
     /**
-     * Use this field to set the output of a ZodUnion to be `oneOf` instead of `allOf`
+     * Used to set the output of a ZodUnion to be `oneOf` instead of `allOf`
      */
     unionOneOf?: boolean;
     /**
-     * Use this field to output this Zod Schema in the components schemas section. Any usage of this Zod Schema will then be transformed into a $ref.
+     * Used to output this Zod Schema in the components schemas section. Any usage of this Zod Schema will then be transformed into a $ref.
      */
     ref?: string;
     /**
-     * Use this field when you are manually adding a Zod Schema to the components section. This controls whether this should be rendered as request (`input`) or response (`output`). Defaults to `output`
+     * Used when you are manually adding a Zod Schema to the components section. This controls whether this should be rendered as request (`input`) or response (`output`). Defaults to `output`
      */
     refType?: CreationType;
     /**
-     * Use this field to set the created type of an effect.
+     * Used to set the created type of an effect.
      */
     effectType?: CreationType | (z.input<T> extends z.output<T> ? z.output<T> extends z.input<T> ? 'same' : never : never);
+    /**
+     * Used to set metadata for a parameter, request header or cookie
+     */
     param?: Partial<oas31.ParameterObject> & {
         example?: TInferred;
         examples?: Record<string, (oas31.ExampleObject & {
             value: TInferred;
         }) | oas31.ReferenceObject>;
         /**
-         * Use this field to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
+         * Used to output this Zod Schema in the components parameters section. Any usage of this Zod Schema will then be transformed into a $ref.
          */
         ref?: string;
     };
+    /**
+     * Used to set data for a response header
+     */
     header?: Partial<oas31.HeaderObject & oas30.HeaderObject> & {
         /**
-         * Use this field to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
+         * Used to output this Zod Schema in the components headers section. Any usage of this Zod Schema will then be transformed into a $ref.
          */
         ref?: string;
     };
+    /**
+     * Used to override the generated type. If this is provided no metadata will be generated.
+     */
+    type?: SchemaObject['type'];
 }
 interface ZodOpenApiExtendMetadata {
     extends: ZodObject<any, any, any, any, any>;
 }
 declare module 'zod' {
     interface ZodType<Output, Def extends ZodTypeDef, Input = Output> {
+        /**
+         * Add OpenAPI metadata to a Zod Type
+         */
         openapi<T extends ZodTypeAny>(this: T, metadata: ZodOpenApiMetadata<T>): T;
     }
     interface ZodTypeDef {
+        /**
+         * OpenAPI metadata
+         */
         openapi?: ZodOpenApiMetadata<ZodTypeAny>;
     }
     interface ZodObjectDef<T extends ZodRawShape = ZodRawShape, UnknownKeys extends UnknownKeysParam = UnknownKeysParam, Catchall extends ZodTypeAny = ZodTypeAny> extends ZodTypeDef {

package/lib-types/openapi3-ts/dist/model/openapi31.d.ts

@@ -88,7 +88,7 @@ export interface OperationObject extends ISpecificationExtension {
     operationId?: string;
     parameters?: (ParameterObject | ReferenceObject)[];
     requestBody?: RequestBodyObject | ReferenceObject;
-    responses: ResponsesObject;
+    responses?: ResponsesObject;
     callbacks?: CallbacksObject;
     deprecated?: boolean;
     security?: SecurityRequirementObject[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-openapi",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
   "keywords": [
     "typescript",
@@ -37,24 +37,24 @@
     "lib*/**/*.json"
   ],
   "scripts": {
-    "build": "yarn copy:types && node esbuild.mjs && node esbuild.esm.mjs && tsc --allowJS false --declaration --emitDeclarationOnly --outDir lib-types --project tsconfig.build.json",
+    "build": "pnpm copy:types && node esbuild.mjs && node esbuild.esm.mjs && tsc --allowJS false --declaration --emitDeclarationOnly --outDir lib-types --project tsconfig.build.json",
     "copy:types": "skuba node scripts/copyTypes.ts",
     "create:docs": " skuba node examples/simple/createSchema.ts && redocly build-docs examples/simple/openapi.yml --output=examples/simple/redoc-static.html",
     "format": "skuba format",
     "lint": "skuba lint",
-    "prepare": "yarn build",
+    "prepare": "pnpm build",
     "test": "skuba test",
     "test:ci": "skuba test --coverage",
     "test:watch": "skuba test --watch"
   },
   "dependencies": {},
   "devDependencies": {
-    "@redocly/cli": "1.8.2",
+    "@redocly/cli": "1.9.1",
     "@types/node": "^20.3.0",
     "eslint-plugin-zod-openapi": "^0.1.0",
-    "openapi3-ts": "4.2.1",
-    "skuba": "7.3.1",
-    "yaml": "2.3.4",
+    "openapi3-ts": "4.2.2",
+    "skuba": "7.5.0",
+    "yaml": "2.4.0",
     "zod": "3.22.4"
   },
   "peerDependencies": {
@@ -71,6 +71,6 @@
     "entryPoint": "src/index.ts",
     "template": "oss-npm-package",
     "type": "package",
-    "version": "6.0.0"
+    "version": "7.4.1"
   }
 }