zod-openapi 2.17.0 → 2.18.0

package/README.md

@@ -31,7 +31,9 @@ pnpm install zod zod-openapi
 
 ### Extend Zod
 
-This mutates Zod to add an extra `.openapi()` method. Call this at the top of your entry point(s).
+This mutates Zod to add an extra `.openapi()` method. Call this at the top of your entry point(s). You can achieve this in two differernt ways, depending on your preference.
+
+#### Subpath Import
 
 ```ts
 import 'zod-openapi/extend';
@@ -40,12 +42,12 @@ import { z } from 'zod';
 z.string().openapi({ description: 'hello world!', example: 'hello world' });
 ```
 
-#### Manual
+#### Manual Extension
 
-This is useful if you have a different instance of Zod that you would like to extend.
+This is useful if you have a specific instance of Zod or a Zod instance from another library that you would like to target.
 
 ```typescript
-import { z } from 'another-lib';
+import { z } from 'zod';
 import { extendZodWithOpenApi } from 'zod-openapi';
 
 extendZodWithOpenApi(z);
@@ -63,7 +65,7 @@ Use the `.openapi()` method to add metadata to a specific Zod type. The `.openap
 |  `effectType`   |                             Use to override the creation type for a [Zod Effect](#zod-effects)                              |
 |    `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)                                  |
+|      `ref`      |                     Use this to [auto register a schema as a re-usable component](#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.                 |
 |  `unionOneOf`   |                           Set to `true` to force a ZodUnion to output `oneOf` instead of `allOf`                            |
@@ -73,8 +75,9 @@ Use the `.openapi()` method to add metadata to a specific Zod type. The `.openap
 Creates an OpenAPI documentation object
 
 ```typescript
+import 'zod-openapi/extend';
 import { z } from 'zod';
-import { createDocument, extendZodWithOpenApi } from 'zod-openapi';
+import { createDocument } from 'zod-openapi';
 
 const jobId = z.string().openapi({
   description: 'A unique identifier for a job',
@@ -116,82 +119,84 @@ const document = createDocument({
 });
 ```
 
-Generates the following object:
-
-```json
-{
-  "openapi": "3.1.0",
-  "info": {
-    "title": "My API",
-    "version": "1.0.0"
-  },
-  "paths": {
-    "/jobs/{jobId}": {
-      "put": {
-        "parameters": [
-          {
-            "in": "path",
-            "name": "jobId",
-            "description": "A unique identifier for a job",
-            "schema": {
-              "$ref": "#/components/schemas/jobId"
-            }
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
+<details>
+  <summary>Creates the following object:</summary>
+  
+  ```json
+  {
+    "openapi": "3.1.0",
+    "info": {
+      "title": "My API",
+      "version": "1.0.0"
+    },
+    "paths": {
+      "/jobs/{jobId}": {
+        "put": {
+          "parameters": [
+            {
+              "in": "path",
+              "name": "jobId",
+              "description": "A unique identifier for a job",
               "schema": {
-                "type": "object",
-                "properties": {
-                  "title": {
-                    "type": "string",
-                    "description": "Job title",
-                    "example": "My job"
-                  }
-                },
-                "required": ["title"]
+                "$ref": "#/components/schemas/jobId"
               }
             }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "200 OK",
+          ],
+          "requestBody": {
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "jobId": {
-                      "$ref": "#/components/schemas/jobId"
-                    },
                     "title": {
                       "type": "string",
                       "description": "Job title",
                       "example": "My job"
                     }
                   },
-                  "required": ["jobId", "title"]
+                  "required": ["title"]
+                }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "200 OK",
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "type": "object",
+                    "properties": {
+                      "jobId": {
+                        "$ref": "#/components/schemas/jobId"
+                      },
+                      "title": {
+                        "type": "string",
+                        "description": "Job title",
+                        "example": "My job"
+                      }
+                    },
+                    "required": ["jobId", "title"]
+                  }
                 }
               }
             }
           }
         }
       }
-    }
-  },
-  "components": {
-    "schemas": {
-      "jobId": {
-        "type": "string",
-        "description": "A unique identifier for a job",
-        "example": "12345"
+    },
+    "components": {
+      "schemas": {
+        "jobId": {
+          "type": "string",
+          "description": "A unique identifier for a job",
+          "example": "12345"
+        }
       }
     }
   }
-}
-```
+  ```
+</details>
 
 ### Request Parameters
 
@@ -283,6 +288,42 @@ createDocument({
 });
 ```
 
+### Callbacks
+
+```typescript
+createDocument({
+  paths: {
+    '/jobs': {
+      get: {
+        callbacks: {
+          onData: {
+            '{$request.query.callbackUrl}/data': {
+              post: {
+                requestBody: {
+                  content: {
+                    'application/json': { schema: z.object({ a: z.string() }) },
+                  },
+                },
+                responses: {
+                  200: {
+                    description: '200 OK',
+                    content: {
+                      'application/json': {
+                        schema: z.object({ a: z.string() }),
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
 ### Creating Components
 
 OpenAPI allows you to define reusable [components](https://swagger.io/docs/specification/components/) and this library allows you to replicate that in two separate ways.
@@ -326,7 +367,7 @@ Wherever `title` is used in schemas across the document, it will instead be crea
 }
 ```
 
-This can be an extremely powerful way to generate better Open API documentation. There are some Open API features like [discriminator mapping](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) which require all schemas in the union to contain a ref.
+This can be an extremely powerful way to create less repetitive Open API documentation. There are some Open API features like [discriminator mapping](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) which require all schemas in the union to contain a ref.
 
 ##### Manually Registering Schema
 
@@ -479,6 +520,53 @@ createDocument({
 });
 ```
 
+#### Callbacks
+
+Callbacks can also be registered
+
+```typescript
+const callback: ZodOpenApiCallbackObject = {
+  ref: 'some-callback'
+  post: {
+    responses: {
+      200: {
+        description: '200 OK',
+        content: {
+          'application/json': {
+            schema: z.object({ a: z.string() }),
+          },
+        },
+      },
+    },
+  },
+};
+
+//or
+
+const callback: ZodOpenApiCallbackObject = {
+  post: {
+    responses: {
+      200: {
+        description: '200 OK',
+        content: {
+          'application/json': {
+            schema: z.object({ a: z.string() }),
+          },
+        },
+      },
+    },
+  },
+};
+
+createDocument({
+  components: {
+    callbacks: {
+      'some-callback': callback,
+    },
+  },
+});
+```
+
 ## Supported OpenAPI Versions
 
 Currently the following versions of OpenAPI are supported
@@ -525,7 +613,7 @@ For example in `z.string().nullable()` will be rendered differently
 - ZodBranded
 - ZodCatch
 - ZodDate
-  - `string` `type` mapping by default
+  - `type` is mapped as `string` by default
 - ZodDefault
 - ZodDiscriminatedUnion
   - `discriminator` mapping when all schemas in the union are [registered](#creating-components). The discriminator must be a `ZodLiteral`, `ZodEnum` or `ZodNativeEnum` with string values. Only values wrapped in `ZodBranded`, `ZodReadOnly` and `ZodCatch` are supported.
@@ -555,7 +643,7 @@ For example in `z.string().nullable()` will be rendered differently
 - ZodReadonly
 - ZodRecord
 - ZodSet
-  - Treated as an array with `uniqueItems` (you may need to add a pre-process)
+  - Treated as an array with `uniqueItems` (you may need to add a pre-process to convert it to a set)
 - ZodString
   - `format` mapping for `.url()`, `.uuid()`, `.email()`, `.datetime()`, `.date()`, `.time()`, `.duration()`
   - `minLength`/`maxLength` mapping for `.length()`, `.min()`, `.max()`

package/lib-commonjs/index.js

@@ -1431,6 +1431,53 @@ var createSchema = (zodSchema, state, subpath) => {
   return schema.schema;
 };
 
+// src/create/content.ts
+var createMediaTypeSchema = (schemaObject, components, type, subpath) => {
+  if (!schemaObject) {
+    return void 0;
+  }
+  if (!isAnyZodType(schemaObject)) {
+    return schemaObject;
+  }
+  return createSchema(
+    schemaObject,
+    {
+      components,
+      type,
+      path: [],
+      visited: /* @__PURE__ */ new Set()
+    },
+    subpath
+  );
+};
+var createMediaTypeObject = (mediaTypeObject, components, type, subpath) => {
+  if (!mediaTypeObject) {
+    return void 0;
+  }
+  return {
+    ...mediaTypeObject,
+    schema: createMediaTypeSchema(mediaTypeObject.schema, components, type, [
+      ...subpath,
+      "schema"
+    ])
+  };
+};
+var createContent = (contentObject, components, type, subpath) => Object.entries(contentObject).reduce(
+  (acc, [mediaType, zodOpenApiMediaTypeObject]) => {
+    const mediaTypeObject = createMediaTypeObject(
+      zodOpenApiMediaTypeObject,
+      components,
+      type,
+      [...subpath, mediaType]
+    );
+    if (mediaTypeObject) {
+      acc[mediaType] = mediaTypeObject;
+    }
+    return acc;
+  },
+  {}
+);
+
 // src/create/parameters.ts
 var createComponentParamRef = (ref) => `#/components/parameters/${ref}`;
 var createBaseParameter = (schema, components, subpath) => {
@@ -1574,53 +1621,6 @@ var getZodObject = (schema, type) => {
   throw new Error("failed to find ZodObject in schema");
 };
 
-// src/create/content.ts
-var createMediaTypeSchema = (schemaObject, components, type, subpath) => {
-  if (!schemaObject) {
-    return void 0;
-  }
-  if (!isAnyZodType(schemaObject)) {
-    return schemaObject;
-  }
-  return createSchema(
-    schemaObject,
-    {
-      components,
-      type,
-      path: [],
-      visited: /* @__PURE__ */ new Set()
-    },
-    subpath
-  );
-};
-var createMediaTypeObject = (mediaTypeObject, components, type, subpath) => {
-  if (!mediaTypeObject) {
-    return void 0;
-  }
-  return {
-    ...mediaTypeObject,
-    schema: createMediaTypeSchema(mediaTypeObject.schema, components, type, [
-      ...subpath,
-      "schema"
-    ])
-  };
-};
-var createContent = (contentObject, components, type, subpath) => Object.entries(contentObject).reduce(
-  (acc, [mediaType, zodOpenApiMediaTypeObject]) => {
-    const mediaTypeObject = createMediaTypeObject(
-      zodOpenApiMediaTypeObject,
-      components,
-      type,
-      [...subpath, mediaType]
-    );
-    if (mediaTypeObject) {
-      acc[mediaType] = mediaTypeObject;
-    }
-    return acc;
-  },
-  {}
-);
-
 // src/create/specificationExtension.ts
 var isISpecificationExtension = (key) => key.startsWith("x-");
 
@@ -1775,11 +1775,17 @@ var createOperation = (operationObject, components, subpath) => {
     components,
     [...subpath, "responses"]
   );
+  const maybeCallbacks = createCallbacks(
+    operationObject.callbacks,
+    components,
+    [...subpath, "callbacks"]
+  );
   return {
     ...rest,
     ...maybeParameters && { parameters: maybeParameters },
     ...maybeRequestBody && { requestBody: maybeRequestBody },
-    ...maybeResponses && { responses: maybeResponses }
+    ...maybeResponses && { responses: maybeResponses },
+    ...maybeCallbacks && { callbacks: maybeCallbacks }
   };
 };
 var createPathItem = (pathObject, components, path) => Object.entries(pathObject).reduce(
@@ -1791,7 +1797,7 @@ var createPathItem = (pathObject, components, path) => Object.entries(pathObject
       acc[key] = createOperation(
         value,
         components,
-        [path, key]
+        [...path, key]
       );
       return acc;
     }
@@ -1810,7 +1816,55 @@ var createPaths = (pathsObject, components) => {
         acc[path] = pathItemObject;
         return acc;
       }
-      acc[path] = createPathItem(pathItemObject, components, path);
+      acc[path] = createPathItem(pathItemObject, components, [path]);
+      return acc;
+    },
+    {}
+  );
+};
+
+// src/create/callbacks.ts
+var createCallback = (callbackObject, components, subpath) => {
+  const { ref, ...callbacks } = callbackObject;
+  const callback = Object.entries(
+    callbacks
+  ).reduce((acc, [callbackName, pathItemObject]) => {
+    if (isISpecificationExtension(callbackName)) {
+      acc[callbackName] = pathItemObject;
+      return acc;
+    }
+    acc[callbackName] = createPathItem(pathItemObject, components, [
+      ...subpath,
+      callbackName
+    ]);
+    return acc;
+  }, {});
+  if (ref) {
+    components.callbacks.set(callbackObject, {
+      type: "complete",
+      ref,
+      callbackObject: callback
+    });
+    return {
+      $ref: createComponentCallbackRef(ref)
+    };
+  }
+  return callback;
+};
+var createCallbacks = (callbacksObject, components, subpath) => {
+  if (!callbacksObject) {
+    return void 0;
+  }
+  return Object.entries(callbacksObject).reduce(
+    (acc, [callbackName, callbackObject]) => {
+      if (isISpecificationExtension(callbackName)) {
+        acc[callbackName] = callbackObject;
+        return acc;
+      }
+      acc[callbackName] = createCallback(callbackObject, components, [
+        ...subpath,
+        callbackName
+      ]);
       return acc;
     },
     {}
@@ -1825,6 +1879,7 @@ var getDefaultComponents = (componentsObject, openapi = "3.1.0") => {
     headers: /* @__PURE__ */ new Map(),
     requestBodies: /* @__PURE__ */ new Map(),
     responses: /* @__PURE__ */ new Map(),
+    callbacks: /* @__PURE__ */ new Map(),
     openapi
   };
   if (!componentsObject) {
@@ -1835,6 +1890,7 @@ var getDefaultComponents = (componentsObject, openapi = "3.1.0") => {
   getRequestBodies(componentsObject.requestBodies, defaultComponents);
   getHeaders(componentsObject.headers, defaultComponents);
   getResponses(componentsObject.responses, defaultComponents);
+  getCallbacks(componentsObject.callbacks, defaultComponents);
   return defaultComponents;
 };
 var getSchemas = (schemas, components) => {
@@ -1935,9 +1991,27 @@ var getRequestBodies = (requestBodies, components) => {
     });
   });
 };
+var getCallbacks = (callbacks, components) => {
+  if (!callbacks) {
+    return;
+  }
+  Object.entries(callbacks).forEach(([key, callback]) => {
+    if (components.callbacks.has(callback)) {
+      throw new Error(
+        `Callback ${JSON.stringify(callback)} is already registered`
+      );
+    }
+    const ref = callback?.ref ?? key;
+    components.callbacks.set(callback, {
+      type: "manual",
+      ref
+    });
+  });
+};
 var createComponentSchemaRef = (schemaRef) => `#/components/schemas/${schemaRef}`;
 var createComponentResponseRef = (responseRef) => `#/components/responses/${responseRef}`;
 var createComponentRequestBodyRef = (requestBodyRef) => `#/components/requestBodies/${requestBodyRef}`;
+var createComponentCallbackRef = (callbackRef) => `#/components/callbacks/${callbackRef}`;
 var createComponents = (componentsObject, components) => {
   const combinedSchemas = createSchemaComponents(componentsObject, components);
   const combinedParameters = createParamComponents(
@@ -1947,6 +2021,7 @@ var createComponents = (componentsObject, components) => {
   const combinedHeaders = createHeaderComponents(componentsObject, components);
   const combinedResponses = createResponseComponents(components);
   const combinedRequestBodies = createRequestBodiesComponents(components);
+  const combinedCallbacks = createCallbackComponents(components);
   const { schemas, parameters, headers, responses, requestBodies, ...rest } = componentsObject;
   const finalComponents = {
     ...rest,
@@ -1954,7 +2029,8 @@ var createComponents = (componentsObject, components) => {
     ...combinedParameters && { parameters: combinedParameters },
     ...combinedRequestBodies && { requestBodies: combinedRequestBodies },
     ...combinedHeaders && { headers: combinedHeaders },
-    ...combinedResponses && { responses: combinedResponses }
+    ...combinedResponses && { responses: combinedResponses },
+    ...combinedCallbacks && { callbacks: combinedCallbacks }
   };
   return Object.keys(finalComponents).length ? finalComponents : void 0;
 };
@@ -2096,6 +2172,23 @@ var createRequestBodiesComponents = (components) => {
   }, {});
   return Object.keys(finalComponents).length ? finalComponents : void 0;
 };
+var createCallbackComponents = (components) => {
+  Array.from(components.callbacks).forEach(([schema, component], index) => {
+    if (component.type === "manual") {
+      createCallback(schema, components, [`component callback ${index}`]);
+    }
+  });
+  const finalComponents = Array.from(components.callbacks).reduce((acc, [_zodType, component]) => {
+    if (component.type === "complete") {
+      if (acc[component.ref]) {
+        throw new Error(`Callback "${component.ref}" is already registered`);
+      }
+      acc[component.ref] = component.callbackObject;
+    }
+    return acc;
+  }, {});
+  return Object.keys(finalComponents).length ? finalComponents : void 0;
+};
 
 // src/create/document.ts
 var createDocument = (zodOpenApiObject) => {

package/lib-esm/index.mjs

@@ -1407,6 +1407,53 @@ var createSchema = (zodSchema, state, subpath) => {
   return schema.schema;
 };
 
+// src/create/content.ts
+var createMediaTypeSchema = (schemaObject, components, type, subpath) => {
+  if (!schemaObject) {
+    return void 0;
+  }
+  if (!isAnyZodType(schemaObject)) {
+    return schemaObject;
+  }
+  return createSchema(
+    schemaObject,
+    {
+      components,
+      type,
+      path: [],
+      visited: /* @__PURE__ */ new Set()
+    },
+    subpath
+  );
+};
+var createMediaTypeObject = (mediaTypeObject, components, type, subpath) => {
+  if (!mediaTypeObject) {
+    return void 0;
+  }
+  return {
+    ...mediaTypeObject,
+    schema: createMediaTypeSchema(mediaTypeObject.schema, components, type, [
+      ...subpath,
+      "schema"
+    ])
+  };
+};
+var createContent = (contentObject, components, type, subpath) => Object.entries(contentObject).reduce(
+  (acc, [mediaType, zodOpenApiMediaTypeObject]) => {
+    const mediaTypeObject = createMediaTypeObject(
+      zodOpenApiMediaTypeObject,
+      components,
+      type,
+      [...subpath, mediaType]
+    );
+    if (mediaTypeObject) {
+      acc[mediaType] = mediaTypeObject;
+    }
+    return acc;
+  },
+  {}
+);
+
 // src/create/parameters.ts
 var createComponentParamRef = (ref) => `#/components/parameters/${ref}`;
 var createBaseParameter = (schema, components, subpath) => {
@@ -1550,53 +1597,6 @@ var getZodObject = (schema, type) => {
   throw new Error("failed to find ZodObject in schema");
 };
 
-// src/create/content.ts
-var createMediaTypeSchema = (schemaObject, components, type, subpath) => {
-  if (!schemaObject) {
-    return void 0;
-  }
-  if (!isAnyZodType(schemaObject)) {
-    return schemaObject;
-  }
-  return createSchema(
-    schemaObject,
-    {
-      components,
-      type,
-      path: [],
-      visited: /* @__PURE__ */ new Set()
-    },
-    subpath
-  );
-};
-var createMediaTypeObject = (mediaTypeObject, components, type, subpath) => {
-  if (!mediaTypeObject) {
-    return void 0;
-  }
-  return {
-    ...mediaTypeObject,
-    schema: createMediaTypeSchema(mediaTypeObject.schema, components, type, [
-      ...subpath,
-      "schema"
-    ])
-  };
-};
-var createContent = (contentObject, components, type, subpath) => Object.entries(contentObject).reduce(
-  (acc, [mediaType, zodOpenApiMediaTypeObject]) => {
-    const mediaTypeObject = createMediaTypeObject(
-      zodOpenApiMediaTypeObject,
-      components,
-      type,
-      [...subpath, mediaType]
-    );
-    if (mediaTypeObject) {
-      acc[mediaType] = mediaTypeObject;
-    }
-    return acc;
-  },
-  {}
-);
-
 // src/create/specificationExtension.ts
 var isISpecificationExtension = (key) => key.startsWith("x-");
 
@@ -1751,11 +1751,17 @@ var createOperation = (operationObject, components, subpath) => {
     components,
     [...subpath, "responses"]
   );
+  const maybeCallbacks = createCallbacks(
+    operationObject.callbacks,
+    components,
+    [...subpath, "callbacks"]
+  );
   return {
     ...rest,
     ...maybeParameters && { parameters: maybeParameters },
     ...maybeRequestBody && { requestBody: maybeRequestBody },
-    ...maybeResponses && { responses: maybeResponses }
+    ...maybeResponses && { responses: maybeResponses },
+    ...maybeCallbacks && { callbacks: maybeCallbacks }
   };
 };
 var createPathItem = (pathObject, components, path) => Object.entries(pathObject).reduce(
@@ -1767,7 +1773,7 @@ var createPathItem = (pathObject, components, path) => Object.entries(pathObject
       acc[key] = createOperation(
         value,
         components,
-        [path, key]
+        [...path, key]
       );
       return acc;
     }
@@ -1786,7 +1792,55 @@ var createPaths = (pathsObject, components) => {
         acc[path] = pathItemObject;
         return acc;
       }
-      acc[path] = createPathItem(pathItemObject, components, path);
+      acc[path] = createPathItem(pathItemObject, components, [path]);
+      return acc;
+    },
+    {}
+  );
+};
+
+// src/create/callbacks.ts
+var createCallback = (callbackObject, components, subpath) => {
+  const { ref, ...callbacks } = callbackObject;
+  const callback = Object.entries(
+    callbacks
+  ).reduce((acc, [callbackName, pathItemObject]) => {
+    if (isISpecificationExtension(callbackName)) {
+      acc[callbackName] = pathItemObject;
+      return acc;
+    }
+    acc[callbackName] = createPathItem(pathItemObject, components, [
+      ...subpath,
+      callbackName
+    ]);
+    return acc;
+  }, {});
+  if (ref) {
+    components.callbacks.set(callbackObject, {
+      type: "complete",
+      ref,
+      callbackObject: callback
+    });
+    return {
+      $ref: createComponentCallbackRef(ref)
+    };
+  }
+  return callback;
+};
+var createCallbacks = (callbacksObject, components, subpath) => {
+  if (!callbacksObject) {
+    return void 0;
+  }
+  return Object.entries(callbacksObject).reduce(
+    (acc, [callbackName, callbackObject]) => {
+      if (isISpecificationExtension(callbackName)) {
+        acc[callbackName] = callbackObject;
+        return acc;
+      }
+      acc[callbackName] = createCallback(callbackObject, components, [
+        ...subpath,
+        callbackName
+      ]);
       return acc;
     },
     {}
@@ -1801,6 +1855,7 @@ var getDefaultComponents = (componentsObject, openapi = "3.1.0") => {
     headers: /* @__PURE__ */ new Map(),
     requestBodies: /* @__PURE__ */ new Map(),
     responses: /* @__PURE__ */ new Map(),
+    callbacks: /* @__PURE__ */ new Map(),
     openapi
   };
   if (!componentsObject) {
@@ -1811,6 +1866,7 @@ var getDefaultComponents = (componentsObject, openapi = "3.1.0") => {
   getRequestBodies(componentsObject.requestBodies, defaultComponents);
   getHeaders(componentsObject.headers, defaultComponents);
   getResponses(componentsObject.responses, defaultComponents);
+  getCallbacks(componentsObject.callbacks, defaultComponents);
   return defaultComponents;
 };
 var getSchemas = (schemas, components) => {
@@ -1911,9 +1967,27 @@ var getRequestBodies = (requestBodies, components) => {
     });
   });
 };
+var getCallbacks = (callbacks, components) => {
+  if (!callbacks) {
+    return;
+  }
+  Object.entries(callbacks).forEach(([key, callback]) => {
+    if (components.callbacks.has(callback)) {
+      throw new Error(
+        `Callback ${JSON.stringify(callback)} is already registered`
+      );
+    }
+    const ref = callback?.ref ?? key;
+    components.callbacks.set(callback, {
+      type: "manual",
+      ref
+    });
+  });
+};
 var createComponentSchemaRef = (schemaRef) => `#/components/schemas/${schemaRef}`;
 var createComponentResponseRef = (responseRef) => `#/components/responses/${responseRef}`;
 var createComponentRequestBodyRef = (requestBodyRef) => `#/components/requestBodies/${requestBodyRef}`;
+var createComponentCallbackRef = (callbackRef) => `#/components/callbacks/${callbackRef}`;
 var createComponents = (componentsObject, components) => {
   const combinedSchemas = createSchemaComponents(componentsObject, components);
   const combinedParameters = createParamComponents(
@@ -1923,6 +1997,7 @@ var createComponents = (componentsObject, components) => {
   const combinedHeaders = createHeaderComponents(componentsObject, components);
   const combinedResponses = createResponseComponents(components);
   const combinedRequestBodies = createRequestBodiesComponents(components);
+  const combinedCallbacks = createCallbackComponents(components);
   const { schemas, parameters, headers, responses, requestBodies, ...rest } = componentsObject;
   const finalComponents = {
     ...rest,
@@ -1930,7 +2005,8 @@ var createComponents = (componentsObject, components) => {
     ...combinedParameters && { parameters: combinedParameters },
     ...combinedRequestBodies && { requestBodies: combinedRequestBodies },
     ...combinedHeaders && { headers: combinedHeaders },
-    ...combinedResponses && { responses: combinedResponses }
+    ...combinedResponses && { responses: combinedResponses },
+    ...combinedCallbacks && { callbacks: combinedCallbacks }
   };
   return Object.keys(finalComponents).length ? finalComponents : void 0;
 };
@@ -2072,6 +2148,23 @@ var createRequestBodiesComponents = (components) => {
   }, {});
   return Object.keys(finalComponents).length ? finalComponents : void 0;
 };
+var createCallbackComponents = (components) => {
+  Array.from(components.callbacks).forEach(([schema, component], index) => {
+    if (component.type === "manual") {
+      createCallback(schema, components, [`component callback ${index}`]);
+    }
+  });
+  const finalComponents = Array.from(components.callbacks).reduce((acc, [_zodType, component]) => {
+    if (component.type === "complete") {
+      if (acc[component.ref]) {
+        throw new Error(`Callback "${component.ref}" is already registered`);
+      }
+      acc[component.ref] = component.callbackObject;
+    }
+    return acc;
+  }, {});
+  return Object.keys(finalComponents).length ? finalComponents : void 0;
+};
 
 // src/create/document.ts
 var createDocument = (zodOpenApiObject) => {

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

@@ -0,0 +1,5 @@
+import type { oas31 } from '../openapi3-ts/dist';
+import { type ComponentsObject } from './components';
+import type { ZodOpenApiCallbackObject } from './document';
+export declare const createCallback: (callbackObject: ZodOpenApiCallbackObject, components: ComponentsObject, subpath: string[]) => oas31.CallbackObject;
+export declare const createCallbacks: (callbacksObject: oas31.CallbackObject | undefined, components: ComponentsObject, subpath: string[]) => oas31.CallbackObject | undefined;

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

@@ -1,6 +1,6 @@
 import type { ZodType } from 'zod';
 import type { oas30, oas31 } from '../openapi3-ts/dist';
-import type { ZodOpenApiComponentsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiVersion } from './document';
+import type { ZodOpenApiCallbackObject, ZodOpenApiComponentsObject, ZodOpenApiRequestBodyObject, ZodOpenApiResponseObject, ZodOpenApiVersion } from './document';
 export type CreationType = 'input' | 'output';
 type BaseEffect = {
     zodType: ZodType;
@@ -95,17 +95,31 @@ export interface PartialRequestBodyComponent extends BaseRequestBodyComponent {
 }
 export type RequestBodyComponent = CompleteRequestBodyComponent | PartialRequestBodyComponent;
 export type RequestBodyComponentMap = Map<ZodOpenApiRequestBodyObject, RequestBodyComponent>;
+export interface BaseCallbackComponent {
+    ref: string;
+}
+export interface CompleteCallbackComponent extends BaseCallbackComponent {
+    type: 'complete';
+    callbackObject: ZodOpenApiCallbackObject | oas31.CallbackObject | oas30.CallbackObject;
+}
+export interface PartialCallbackComponent extends BaseCallbackComponent {
+    type: 'manual';
+}
+export type CallbackComponent = CompleteCallbackComponent | PartialCallbackComponent;
+export type CallbackComponentMap = Map<ZodOpenApiCallbackObject, CallbackComponent>;
 export interface ComponentsObject {
     schemas: SchemaComponentMap;
     parameters: ParameterComponentMap;
     headers: HeaderComponentMap;
     requestBodies: RequestBodyComponentMap;
     responses: ResponseComponentMap;
+    callbacks: CallbackComponentMap;
     openapi: ZodOpenApiVersion;
 }
 export declare const getDefaultComponents: (componentsObject?: ZodOpenApiComponentsObject, openapi?: ZodOpenApiVersion) => ComponentsObject;
 export declare const createComponentSchemaRef: (schemaRef: string) => string;
 export declare const createComponentResponseRef: (responseRef: string) => string;
 export declare const createComponentRequestBodyRef: (requestBodyRef: string) => string;
+export declare const createComponentCallbackRef: (callbackRef: string) => string;
 export declare const createComponents: (componentsObject: ZodOpenApiComponentsObject, components: ComponentsObject) => oas31.ComponentsObject | undefined;
 export {};

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

@@ -26,11 +26,20 @@ export interface ZodOpenApiResponsesObject extends oas31.ISpecificationExtension
 export type ZodOpenApiParameters = {
     [type in oas31.ParameterLocation & oas30.ParameterLocation]?: ZodObjectInputType;
 };
-export interface ZodOpenApiOperationObject extends Omit<oas31.OperationObject & oas30.OperationObject, 'requestBody' | 'responses' | 'parameters'> {
+export interface ZodOpenApiCallbacksObject extends oas31.ISpecificationExtension {
+    [name: string]: ZodOpenApiCallbackObject;
+}
+export interface ZodOpenApiCallbackObject extends oas31.ISpecificationExtension {
+    /** Use this field to auto register this callback object as a component */
+    ref?: string;
+    [name: string]: ZodOpenApiPathItemObject | string | undefined;
+}
+export interface ZodOpenApiOperationObject extends Omit<oas31.OperationObject & oas30.OperationObject, 'requestBody' | 'responses' | 'parameters' | 'callbacks'> {
     parameters?: Array<ZodType | oas31.ParameterObject | oas30.ParameterObject | oas31.ReferenceObject | oas30.ReferenceObject>;
     requestBody?: ZodOpenApiRequestBodyObject;
     requestParams?: ZodOpenApiParameters;
     responses: ZodOpenApiResponsesObject;
+    callbacks?: ZodOpenApiCallbacksObject;
 }
 export interface ZodOpenApiPathItemObject extends Omit<oas31.PathItemObject & oas30.PathItemObject, 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace'> {
     get?: ZodOpenApiOperationObject;
@@ -51,6 +60,7 @@ export interface ZodOpenApiComponentsObject extends Omit<oas31.ComponentsObject
     requestBodies?: Record<string, ZodOpenApiRequestBodyObject>;
     headers?: Record<string, ZodType | oas31.HeaderObject | oas30.HeaderObject | oas31.ReferenceObject | oas30.ReferenceObject>;
     responses?: Record<string, ZodOpenApiResponseObject>;
+    callbacks?: Record<string, ZodOpenApiCallbackObject>;
 }
 export type ZodOpenApiVersion = OpenApiVersion;
 export interface ZodOpenApiObject extends Omit<oas31.OpenAPIObject, 'openapi' | 'paths' | 'webhooks' | 'components'> {

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

@@ -1,5 +1,6 @@
 import type { oas31 } from '../openapi3-ts/dist';
 import { type ComponentsObject } from './components';
-import type { ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject } from './document';
+import type { ZodOpenApiPathItemObject, ZodOpenApiPathsObject, ZodOpenApiRequestBodyObject } from './document';
 export declare const createRequestBody: (requestBodyObject: ZodOpenApiRequestBodyObject | undefined, components: ComponentsObject, subpath: string[]) => oas31.ReferenceObject | oas31.RequestBodyObject | undefined;
+export declare const createPathItem: (pathObject: ZodOpenApiPathItemObject, components: ComponentsObject, path: string[]) => oas31.PathItemObject;
 export declare const createPaths: (pathsObject: ZodOpenApiPathsObject | undefined, components: ComponentsObject) => oas31.PathsObject | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-openapi",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "Convert Zod Schemas to OpenAPI v3.x documentation",
   "keywords": [
     "typescript",
@@ -67,17 +67,18 @@
     "test:watch": "skuba test --watch"
   },
   "devDependencies": {
-    "@redocly/cli": "1.11.0",
+    "@redocly/cli": "1.14.0",
     "@types/node": "^20.3.0",
     "eslint-plugin-zod-openapi": "^0.1.0",
-    "openapi3-ts": "4.3.1",
+    "openapi3-ts": "4.3.2",
     "skuba": "8.0.1",
-    "yaml": "2.4.1",
-    "zod": "3.23.3"
+    "yaml": "2.4.2",
+    "zod": "3.23.8"
   },
   "peerDependencies": {
     "zod": "^3.21.4"
   },
+  "packageManager": "pnpm@9.0.5",
   "engines": {
     "node": ">=16.11"
   },

package/lib-types/openapi3-ts/oas30.d.ts

@@ -1 +0,0 @@
-export * from './dist/oas30';

package/lib-types/openapi3-ts/oas31.d.ts

@@ -1 +0,0 @@
-export * from './dist/oas31';