docs: add documentation for Zod 4 and Zod Mini

Author: mrlubos

.changeset/mighty-eels-care.md

@@ -0,0 +1,37 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat(zod): add support for Zod 4 and Zod Mini
+
+### Added Zod 4 and Zod Mini
+
+This release adds support for Zod 4 and Zod Mini. By default, the `zod` plugin will generate output for Zod 4. If you want to preserve the previous output for Zod 3 or use Zod Mini, set `compatibilityVersion` to `3` or `mini`.
+
+```js
+export default {
+  input: 'https://get.heyapi.dev/hey-api/backend',
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 3,
+    },
+  ],
+};
+```
+
+```js
+export default {
+  input: 'https://get.heyapi.dev/hey-api/backend',
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 'mini',
+    },
+  ],
+};
+```

docs/openapi-ts/migrating.md

@@ -7,6 +7,44 @@ description: Migrating to @hey-api/openapi-ts.
 
 While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
 
+## v0.80.0
+
+### Added Zod 4 and Zod Mini
+
+This release adds support for Zod 4 and Zod Mini. By default, the `zod` plugin will generate output for Zod 4. If you want to preserve the previous output for Zod 3 or use Zod Mini, set `compatibilityVersion` to `3` or `mini`.
+
+::: code-group
+
+```js [Zod 3]
+export default {
+  input: 'https://get.heyapi.dev/hey-api/backend',
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 3, // [!code ++]
+    },
+  ],
+};
+```
+
+```js [Zod Mini]
+export default {
+  input: 'https://get.heyapi.dev/hey-api/backend',
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 'mini', // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
 ## v0.79.0
 
 ### Removed `typescript+namespace` enums mode

docs/openapi-ts/plugins/zod.md

@@ -91,14 +91,14 @@ export default {
 const zData = z.object({
   body: z
     .object({
-      foo: z.string().optional(),
-      bar: z.union([z.number(), z.null()]).optional(),
+      foo: z.optional(z.string()),
+      bar: z.optional(z.union([z.number(), z.null()])),
     })
     .optional(),
   path: z.object({
     baz: z.string(),
   }),
-  query: z.never().optional(),
+  query: z.optional(z.never()),
 });
 ```
 
@@ -133,10 +133,10 @@ export default {
 ```ts [output]
 const zResponse = z.union([
   z.object({
-    foo: z.string().optional(),
+    foo: z.optional(z.string()),
   }),
   z.object({
-    bar: z.number().optional(),
+    bar: z.optional(z.number()),
   }),
 ]);
 ```
@@ -166,10 +166,10 @@ export default {
 ```
 
 ```ts [output]
-const zFoo = z.number().int();
+const zFoo = z.int();
 
 const zBar = z.object({
-  bar: z.array(z.number().int()).optional(),
+  bar: z.optional(z.array(z.int())),
 });
 ```
 
@@ -198,7 +198,9 @@ export default {
 ```
 
 ```ts [output]
-export const zFoo = z.string().describe('Additional metadata');
+export const zFoo = z.string().register(z.globalRegistry, {
+  description: 'Additional metadata',
+});
 ```
 
 :::

docs/openapi-ts/plugins/zod/mini.md

@@ -37,7 +37,10 @@ export default {
   output: 'src/client',
   plugins: [
     // ...other plugins
-    'zod', // [!code ++]
+    {
+      compatibilityVersion: 'mini', // [!code ++]
+      name: 'zod', // [!code ++]
+    },
   ],
 };
 ```
@@ -91,14 +94,14 @@ export default {
 const zData = z.object({
   body: z
     .object({
-      foo: z.string().optional(),
-      bar: z.union([z.number(), z.null()]).optional(),
+      foo: z.optional(z.string()),
+      bar: z.optional(z.union([z.number(), z.null()])),
     })
     .optional(),
   path: z.object({
     baz: z.string(),
   }),
-  query: z.never().optional(),
+  query: z.optional(z.never()),
 });
 ```
 
@@ -133,10 +136,10 @@ export default {
 ```ts [output]
 const zResponse = z.union([
   z.object({
-    foo: z.string().optional(),
+    foo: z.optional(z.string()),
   }),
   z.object({
-    bar: z.number().optional(),
+    bar: z.optional(z.number()),
   }),
 ]);
 ```
@@ -166,10 +169,10 @@ export default {
 ```
 
 ```ts [output]
-const zFoo = z.number().int();
+const zFoo = z.int();
 
 const zBar = z.object({
-  bar: z.array(z.number().int()).optional(),
+  bar: z.optional(z.array(z.int())),
 });
 ```
 
@@ -198,7 +201,9 @@ export default {
 ```
 
 ```ts [output]
-export const zFoo = z.string().describe('Additional metadata');
+export const zFoo = z.string().register(z.globalRegistry, {
+  description: 'Additional metadata',
+});
 ```
 
 :::

docs/openapi-ts/plugins/zod/v3.md

@@ -14,7 +14,7 @@ import ZodHeading from './ZodHeading.vue';
 
 ### About
 
-[Zod](https://zod.dev) is a TypeScript-first schema validation library with static type inference.
+[Zod](https://v3.zod.dev/) is a TypeScript-first schema validation library with static type inference.
 
 <!-- ### Demo
 
@@ -37,7 +37,10 @@ export default {
   output: 'src/client',
   plugins: [
     // ...other plugins
-    'zod', // [!code ++]
+    {
+      compatibilityVersion: 3, // [!code ++]
+      name: 'zod', // [!code ++]
+    },
   ],
 };
 ```
@@ -105,7 +108,7 @@ const zData = z.object({
 :::
 
 ::: tip
-If you need to access individual fields, you can do so using the [`.shape`](https://zod.dev/api?id=shape) API. For example, we can get the request body schema with `zData.shape.body`.
+If you need to access individual fields, you can do so using the [`.shape`](https://v3.zod.dev/?id=shape) API. For example, we can get the request body schema with `zData.shape.body`.
 :::
 
 You can customize the naming and casing pattern for `requests` schemas using the `.name` and `.case` options.
@@ -179,7 +182,7 @@ You can customize the naming and casing pattern for `definitions` schemas using
 
 ## Metadata
 
-It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
+It's often useful to associate a schema with some additional [metadata](https://v3.zod.dev/?id=describe) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
 
 ::: code-group