zod-openapi 2.10.0 → 2.12.0

package/README.md

@@ -182,7 +182,7 @@ Query, Path, Header & Cookie parameters can be created using the `requestParams`
 ```typescript
 createDocument({
   paths: {
-    '/jobs/:a': {
+    '/jobs/{a}': {
       put: {
         requestParams: {
           path: z.object({ a: z.string() }),
@@ -201,7 +201,7 @@ If you would like to declare parameters in a more traditional way you may also d
 ```ts
 createDocument({
   paths: {
-    '/jobs/:a': {
+    '/jobs/{a}': {
       put: {
         parameters: [
           z.string().openapi({
@@ -521,6 +521,7 @@ For example in `z.string().nullable()` will be rendered differently
 - ZodLiteral
 - ZodNativeEnum
   - supporting `string`, `number` and combined enums.
+- ZodNever
 - ZodNull
 - ZodNullable
 - ZodNumber
@@ -543,6 +544,7 @@ For example in `z.string().nullable()` will be rendered differently
 - ZodTuple
   - `items` mapping for `.rest()`
   - `prefixItems` mapping for OpenAPI 3.1.0+
+- ZodUndefined
 - ZodUnion
   - By default it outputs an `allOf` schema. Use `unionOneOf` to change this to output `oneOf` instead.
 - ZodUnknown

package/lib-commonjs/index.js

@@ -34,9 +34,20 @@ var isAnyZodType = (zodType) => Boolean(
   zodType?._def?.typeName
 );
 
+// src/openapi.ts
+var openApiVersions = [
+  "3.0.0",
+  "3.0.1",
+  "3.0.2",
+  "3.0.3",
+  "3.1.0"
+];
+var satisfiesVersion = (test, against) => openApiVersions.indexOf(test) >= openApiVersions.indexOf(against);
+var isReferenceObject = (schemaOrRef) => Boolean("$ref" in schemaOrRef && schemaOrRef.$ref);
+
 // src/create/schema/metadata.ts
 var enhanceWithMetadata = (schemaObject, metadata) => {
-  if ("$ref" in schemaObject) {
+  if (isReferenceObject(schemaObject)) {
     if (Object.values(metadata).every((val) => val === void 0)) {
       return schemaObject;
     }
@@ -171,17 +182,11 @@ var createLiteralSchema = (zodLiteral) => ({
 // src/create/schema/parsers/manual.ts
 var createManualTypeSchema = (zodSchema, state) => {
   if (!zodSchema._def.openapi?.type) {
-    const zodType = zodSchema.constructor.name;
-    if (isZodType(zodSchema, "ZodEffects")) {
-      const schemaName = `${zodType} - ${zodSchema._def.effect.type}`;
-      throw new Error(
-        `Unknown schema ${schemaName} at ${state.path.join(
-          " > "
-        )}. Please assign it a manual 'type', wrap it in a ZodPipeline or change the 'effectType'.`
-      );
-    }
+    const schemaName = zodSchema.constructor.name;
     throw new Error(
-      `Unknown schema ${zodType}. Please assign it a manual 'type'.`
+      `Unknown schema ${schemaName} at ${state.path.join(
+        " > "
+      )}. Please assign it a manual 'type'.`
     );
   }
   return {
@@ -189,16 +194,6 @@ var createManualTypeSchema = (zodSchema, state) => {
   };
 };
 
-// src/openapi.ts
-var openApiVersions = [
-  "3.0.0",
-  "3.0.1",
-  "3.0.2",
-  "3.0.3",
-  "3.1.0"
-];
-var satisfiesVersion = (test, against) => openApiVersions.indexOf(test) >= openApiVersions.indexOf(against);
-
 // src/create/schema/parsers/nativeEnum.ts
 var createNativeEnumSchema = (zodEnum, state) => {
   const enumValues = getValidEnumValues(zodEnum._def.values);
@@ -248,34 +243,41 @@ var createNullableSchema = (zodNullable, state) => {
   const schemaObject = createSchemaObject(zodNullable.unwrap(), state, [
     "nullable"
   ]);
-  if ("$ref" in schemaObject || schemaObject.allOf) {
-    return {
-      oneOf: mapNullOf([schemaObject], state.components.openapi)
-    };
-  }
-  if (schemaObject.oneOf) {
-    const { oneOf, ...schema2 } = schemaObject;
+  if (satisfiesVersion(state.components.openapi, "3.1.0")) {
+    if (isReferenceObject(schemaObject) || schemaObject.allOf) {
+      return {
+        oneOf: mapNullOf([schemaObject], state.components.openapi)
+      };
+    }
+    if (schemaObject.oneOf) {
+      const { oneOf, ...schema3 } = schemaObject;
+      return {
+        oneOf: mapNullOf(oneOf, state.components.openapi),
+        ...schema3
+      };
+    }
+    if (schemaObject.anyOf) {
+      const { anyOf, ...schema3 } = schemaObject;
+      return {
+        anyOf: mapNullOf(anyOf, state.components.openapi),
+        ...schema3
+      };
+    }
+    const { type: type2, ...schema2 } = schemaObject;
     return {
-      oneOf: mapNullOf(oneOf, state.components.openapi),
+      type: mapNullType(type2),
       ...schema2
     };
   }
-  if (schemaObject.anyOf) {
-    const { anyOf, ...schema2 } = schemaObject;
+  if (isReferenceObject(schemaObject)) {
     return {
-      anyOf: mapNullOf(anyOf, state.components.openapi),
-      ...schema2
+      allOf: [schemaObject],
+      nullable: true
     };
   }
   const { type, ...schema } = schemaObject;
-  if (satisfiesVersion(state.components.openapi, "3.1.0")) {
-    return {
-      type: mapNullType(type),
-      ...schema
-    };
-  }
   return {
-    type,
+    ...type && { type },
     nullable: true,
     ...schema,
     // https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2019-10-31-Clarify-Nullable.md#if-a-schema-specifies-nullable-true-and-enum-1-2-3-does-that-schema-allow-null-values-see-1900
@@ -349,7 +351,7 @@ var createOptionalSchema = (zodOptional, state) => (
   createSchemaObject(zodOptional.unwrap(), state, ["optional"])
 );
 var isOptionalSchema = (zodSchema, state) => {
-  if (isZodType(zodSchema, "ZodOptional")) {
+  if (isZodType(zodSchema, "ZodOptional") || isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined")) {
     return true;
   }
   if (isZodType(zodSchema, "ZodDefault")) {
@@ -489,6 +491,9 @@ var mapRequired = (shape, state) => {
 };
 var mapProperties = (shape, state) => Object.entries(shape).reduce(
   (acc, [key, zodSchema]) => {
+    if (isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined")) {
+      return acc;
+    }
     acc[key] = createSchemaObject(zodSchema, state, [`property: ${key}`]);
     return acc;
   },
@@ -546,7 +551,6 @@ var createRecordSchema = (zodRecord, state) => {
   if (satisfiesVersion(state.components.openapi, "3.1.0") && "type" in renderedKeySchema && renderedKeySchema.type === "string" && Object.keys(renderedKeySchema).length > 1) {
     return {
       type: "object",
-      // @ts-expect-error FIXME: https://github.com/metadevpro/openapi3-ts/pull/120
       propertyNames: keySchema,
       additionalProperties
     };
@@ -674,7 +678,7 @@ var mapStringFormat = (zodStringChecks) => {
 // src/create/schema/parsers/transform.ts
 var createTransformSchema = (zodTransform, state) => {
   if (zodTransform._def.openapi?.effectType === "output") {
-    return createManualTypeSchema(zodTransform, state);
+    return createManualOutputTransformSchema(zodTransform, state);
   }
   if (zodTransform._def.openapi?.effectType === "input") {
     return createSchemaObject(zodTransform._def.schema, state, [
@@ -682,13 +686,27 @@ var createTransformSchema = (zodTransform, state) => {
     ]);
   }
   if (state.type === "output") {
-    return createManualTypeSchema(zodTransform, state);
+    return createManualOutputTransformSchema(zodTransform, state);
   }
   state.effectType = "input";
   return createSchemaObject(zodTransform._def.schema, state, [
     "transform input"
   ]);
 };
+var createManualOutputTransformSchema = (zodTransform, state) => {
+  if (!zodTransform._def.openapi?.type) {
+    const zodType = zodTransform.constructor.name;
+    const schemaName = `${zodType} - ${zodTransform._def.effect.type}`;
+    throw new Error(
+      `Failed to determine a type for ${schemaName} at ${state.path.join(
+        " > "
+      )}. Please change the 'effectType' to 'input', wrap it in a ZodPipeline or assign it a manual 'type'.`
+    );
+  }
+  return {
+    type: zodTransform._def.openapi.type
+  };
+};
 var throwTransformError = (zodType, state) => {
   throw new Error(
     `${JSON.stringify(zodType)} at ${state.path.join(
@@ -980,7 +998,9 @@ var createBaseParameter = (schema, components, subpath) => {
     "schema"
   ]);
   const required = !isOptionalSchema(schema, state);
+  const description = schema._def.openapi?.description ?? schema._def.description;
   return {
+    ...description && { description },
     ...rest,
     ...schema && { schema: schemaObject },
     ...required && { required }

package/lib-esm/index.js

@@ -10,9 +10,20 @@ var isAnyZodType = (zodType) => Boolean(
   zodType?._def?.typeName
 );
 
+// src/openapi.ts
+var openApiVersions = [
+  "3.0.0",
+  "3.0.1",
+  "3.0.2",
+  "3.0.3",
+  "3.1.0"
+];
+var satisfiesVersion = (test, against) => openApiVersions.indexOf(test) >= openApiVersions.indexOf(against);
+var isReferenceObject = (schemaOrRef) => Boolean("$ref" in schemaOrRef && schemaOrRef.$ref);
+
 // src/create/schema/metadata.ts
 var enhanceWithMetadata = (schemaObject, metadata) => {
-  if ("$ref" in schemaObject) {
+  if (isReferenceObject(schemaObject)) {
     if (Object.values(metadata).every((val) => val === void 0)) {
       return schemaObject;
     }
@@ -147,17 +158,11 @@ var createLiteralSchema = (zodLiteral) => ({
 // src/create/schema/parsers/manual.ts
 var createManualTypeSchema = (zodSchema, state) => {
   if (!zodSchema._def.openapi?.type) {
-    const zodType = zodSchema.constructor.name;
-    if (isZodType(zodSchema, "ZodEffects")) {
-      const schemaName = `${zodType} - ${zodSchema._def.effect.type}`;
-      throw new Error(
-        `Unknown schema ${schemaName} at ${state.path.join(
-          " > "
-        )}. Please assign it a manual 'type', wrap it in a ZodPipeline or change the 'effectType'.`
-      );
-    }
+    const schemaName = zodSchema.constructor.name;
     throw new Error(
-      `Unknown schema ${zodType}. Please assign it a manual 'type'.`
+      `Unknown schema ${schemaName} at ${state.path.join(
+        " > "
+      )}. Please assign it a manual 'type'.`
     );
   }
   return {
@@ -165,16 +170,6 @@ var createManualTypeSchema = (zodSchema, state) => {
   };
 };
 
-// src/openapi.ts
-var openApiVersions = [
-  "3.0.0",
-  "3.0.1",
-  "3.0.2",
-  "3.0.3",
-  "3.1.0"
-];
-var satisfiesVersion = (test, against) => openApiVersions.indexOf(test) >= openApiVersions.indexOf(against);
-
 // src/create/schema/parsers/nativeEnum.ts
 var createNativeEnumSchema = (zodEnum, state) => {
   const enumValues = getValidEnumValues(zodEnum._def.values);
@@ -224,34 +219,41 @@ var createNullableSchema = (zodNullable, state) => {
   const schemaObject = createSchemaObject(zodNullable.unwrap(), state, [
     "nullable"
   ]);
-  if ("$ref" in schemaObject || schemaObject.allOf) {
-    return {
-      oneOf: mapNullOf([schemaObject], state.components.openapi)
-    };
-  }
-  if (schemaObject.oneOf) {
-    const { oneOf, ...schema2 } = schemaObject;
+  if (satisfiesVersion(state.components.openapi, "3.1.0")) {
+    if (isReferenceObject(schemaObject) || schemaObject.allOf) {
+      return {
+        oneOf: mapNullOf([schemaObject], state.components.openapi)
+      };
+    }
+    if (schemaObject.oneOf) {
+      const { oneOf, ...schema3 } = schemaObject;
+      return {
+        oneOf: mapNullOf(oneOf, state.components.openapi),
+        ...schema3
+      };
+    }
+    if (schemaObject.anyOf) {
+      const { anyOf, ...schema3 } = schemaObject;
+      return {
+        anyOf: mapNullOf(anyOf, state.components.openapi),
+        ...schema3
+      };
+    }
+    const { type: type2, ...schema2 } = schemaObject;
     return {
-      oneOf: mapNullOf(oneOf, state.components.openapi),
+      type: mapNullType(type2),
       ...schema2
     };
   }
-  if (schemaObject.anyOf) {
-    const { anyOf, ...schema2 } = schemaObject;
+  if (isReferenceObject(schemaObject)) {
     return {
-      anyOf: mapNullOf(anyOf, state.components.openapi),
-      ...schema2
+      allOf: [schemaObject],
+      nullable: true
     };
   }
   const { type, ...schema } = schemaObject;
-  if (satisfiesVersion(state.components.openapi, "3.1.0")) {
-    return {
-      type: mapNullType(type),
-      ...schema
-    };
-  }
   return {
-    type,
+    ...type && { type },
     nullable: true,
     ...schema,
     // https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2019-10-31-Clarify-Nullable.md#if-a-schema-specifies-nullable-true-and-enum-1-2-3-does-that-schema-allow-null-values-see-1900
@@ -325,7 +327,7 @@ var createOptionalSchema = (zodOptional, state) => (
   createSchemaObject(zodOptional.unwrap(), state, ["optional"])
 );
 var isOptionalSchema = (zodSchema, state) => {
-  if (isZodType(zodSchema, "ZodOptional")) {
+  if (isZodType(zodSchema, "ZodOptional") || isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined")) {
     return true;
   }
   if (isZodType(zodSchema, "ZodDefault")) {
@@ -465,6 +467,9 @@ var mapRequired = (shape, state) => {
 };
 var mapProperties = (shape, state) => Object.entries(shape).reduce(
   (acc, [key, zodSchema]) => {
+    if (isZodType(zodSchema, "ZodNever") || isZodType(zodSchema, "ZodUndefined")) {
+      return acc;
+    }
     acc[key] = createSchemaObject(zodSchema, state, [`property: ${key}`]);
     return acc;
   },
@@ -522,7 +527,6 @@ var createRecordSchema = (zodRecord, state) => {
   if (satisfiesVersion(state.components.openapi, "3.1.0") && "type" in renderedKeySchema && renderedKeySchema.type === "string" && Object.keys(renderedKeySchema).length > 1) {
     return {
       type: "object",
-      // @ts-expect-error FIXME: https://github.com/metadevpro/openapi3-ts/pull/120
       propertyNames: keySchema,
       additionalProperties
     };
@@ -650,7 +654,7 @@ var mapStringFormat = (zodStringChecks) => {
 // src/create/schema/parsers/transform.ts
 var createTransformSchema = (zodTransform, state) => {
   if (zodTransform._def.openapi?.effectType === "output") {
-    return createManualTypeSchema(zodTransform, state);
+    return createManualOutputTransformSchema(zodTransform, state);
   }
   if (zodTransform._def.openapi?.effectType === "input") {
     return createSchemaObject(zodTransform._def.schema, state, [
@@ -658,13 +662,27 @@ var createTransformSchema = (zodTransform, state) => {
     ]);
   }
   if (state.type === "output") {
-    return createManualTypeSchema(zodTransform, state);
+    return createManualOutputTransformSchema(zodTransform, state);
   }
   state.effectType = "input";
   return createSchemaObject(zodTransform._def.schema, state, [
     "transform input"
   ]);
 };
+var createManualOutputTransformSchema = (zodTransform, state) => {
+  if (!zodTransform._def.openapi?.type) {
+    const zodType = zodTransform.constructor.name;
+    const schemaName = `${zodType} - ${zodTransform._def.effect.type}`;
+    throw new Error(
+      `Failed to determine a type for ${schemaName} at ${state.path.join(
+        " > "
+      )}. Please change the 'effectType' to 'input', wrap it in a ZodPipeline or assign it a manual 'type'.`
+    );
+  }
+  return {
+    type: zodTransform._def.openapi.type
+  };
+};
 var throwTransformError = (zodType, state) => {
   throw new Error(
     `${JSON.stringify(zodType)} at ${state.path.join(
@@ -956,7 +974,9 @@ var createBaseParameter = (schema, components, subpath) => {
     "schema"
   ]);
   const required = !isOptionalSchema(schema, state);
+  const description = schema._def.openapi?.description ?? schema._def.description;
   return {
+    ...description && { description },
     ...rest,
     ...schema && { schema: schemaObject },
     ...required && { required }

package/lib-types/create/schema/parsers/nullable.d.ts

@@ -1,4 +1,4 @@
 import type { ZodNullable, ZodTypeAny } from 'zod';
 import type { oas31 } from '../../../openapi3-ts/dist';
 import { type SchemaState } from '../../schema';
-export declare const createNullableSchema: <T extends ZodTypeAny>(zodNullable: ZodNullable<T>, state: SchemaState) => oas31.SchemaObject;
+export declare const createNullableSchema: <T extends ZodTypeAny>(zodNullable: ZodNullable<T>, state: SchemaState) => oas31.SchemaObject | oas31.ReferenceObject;

package/lib-types/create/schema/parsers/transform.d.ts

@@ -2,4 +2,5 @@ import type { ZodEffects, ZodType, ZodTypeAny, input, output } from 'zod';
 import type { oas31 } from '../../../openapi3-ts/dist';
 import { type SchemaState } from '../../schema';
 export declare const createTransformSchema: <T extends ZodTypeAny, Output = output<T>, Input = input<T>>(zodTransform: ZodEffects<T, Output, Input>, state: SchemaState) => oas31.SchemaObject | oas31.ReferenceObject;
+export declare const createManualOutputTransformSchema: <T extends ZodTypeAny, Output = output<T>, Input = input<T>>(zodTransform: ZodEffects<T, Output, Input>, state: SchemaState) => oas31.SchemaObject;
 export declare const throwTransformError: (zodType: ZodType, state: SchemaState) => never;

package/lib-types/openapi.d.ts

@@ -1,3 +1,5 @@
+import type { oas31 } from './openapi3-ts/dist';
 export declare const openApiVersions: readonly ["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0"];
 export type OpenApiVersion = (typeof openApiVersions)[number];
 export declare const satisfiesVersion: (test: OpenApiVersion, against: OpenApiVersion) => boolean;
+export declare const isReferenceObject: (schemaOrRef: oas31.SchemaObject | oas31.ReferenceObject) => schemaOrRef is oas31.ReferenceObject;

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

@@ -28,6 +28,7 @@ export interface ContactObject extends ISpecificationExtension {
 }
 export interface LicenseObject extends ISpecificationExtension {
     name: string;
+    identifier?: string;
     url?: string;
 }
 export interface ComponentsObject extends ISpecificationExtension {
@@ -225,6 +226,7 @@ export interface SchemaObject extends ISpecificationExtension {
         [propertyName: string]: SchemaObject | ReferenceObject;
     };
     additionalProperties?: SchemaObject | ReferenceObject | boolean;
+    propertyNames?: SchemaObject | ReferenceObject;
     description?: string;
     default?: any;
     title?: string;
@@ -244,6 +246,8 @@ export interface SchemaObject extends ISpecificationExtension {
     required?: string[];
     enum?: any[];
     prefixItems?: (SchemaObject | ReferenceObject)[];
+    contentMediaType?: string;
+    contentEncoding?: string;
 }
 export declare function isSchemaObject(schema: SchemaObject | ReferenceObject): schema is SchemaObject;
 export interface SchemasObject {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-openapi",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
   "keywords": [
     "typescript",
@@ -43,12 +43,12 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@redocly/cli": "1.4.0",
+    "@redocly/cli": "1.6.0",
     "@types/node": "^20.3.0",
     "eslint-plugin-zod-openapi": "^0.1.0",
-    "openapi3-ts": "4.1.2",
-    "skuba": "7.2.0",
-    "yaml": "2.3.3",
+    "openapi3-ts": "4.2.1",
+    "skuba": "7.3.1",
+    "yaml": "2.3.4",
     "zod": "3.22.4"
   },
   "peerDependencies": {