Feature: Add Zod v4 .meta() Support for Enhanced OpenAPI Metadata

docs/openapi-ts/plugins/zod.md

@@ -240,6 +240,8 @@ export default {
 
 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.
 
+> If you wish to generate metadata for individual parameters with the zod v4 api, you can set `metadata` to `'local'` to use the `.meta()` method.
+
 ::: code-group
 
 ```ts [example]

packages/openapi-ts-tests/zod/v4/__snapshots__/3.0.x/mini/validators-parameter-example/zod.gen.ts

@@ -0,0 +1,46 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import * as z from 'zod/mini';
+
+export const zUser = z.object({
+    id: z.optional(z.int()),
+    name: z.optional(z.string())
+});
+
+export const zGetUsersData = z.object({
+    body: z.optional(z.never()),
+    path: z.optional(z.never()),
+    query: z.optional(z.object({
+        sort: z.optional(z.string().register(z.globalRegistry, {
+            description: 'Sort order for results',
+            example: [
+                'name,desc'
+            ]
+        })),
+        filter: z.optional(z.string().register(z.globalRegistry, {
+            description: 'Filter criteria',
+            example: [
+                'status:active'
+            ]
+        })),
+        limit: z.optional(z.int().check(z.gte(1), z.lte(100)).register(z.globalRegistry, {
+            description: 'Number of results per page',
+            example: [
+                25
+            ]
+        })),
+        search: z.optional(z.string().register(z.globalRegistry, {
+            description: 'Search query',
+            example: [
+                'john doe'
+            ]
+        }))
+    }))
+});
+
+/**
+ * OK
+ */
+export const zGetUsersResponse = z.array(zUser).register(z.globalRegistry, {
+    description: 'OK'
+});

packages/openapi-ts-tests/zod/v4/__snapshots__/3.0.x/v3/validators-parameter-example/zod.gen.ts

@@ -0,0 +1,24 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { z } from 'zod/v3';
+
+export const zUser = z.object({
+    id: z.number().int().optional(),
+    name: z.string().optional()
+});
+
+export const zGetUsersData = z.object({
+    body: z.never().optional(),
+    path: z.never().optional(),
+    query: z.object({
+        sort: z.string().describe('Sort order for results').optional(),
+        filter: z.string().describe('Filter criteria').optional(),
+        limit: z.number().int().gte(1).lte(100).describe('Number of results per page').optional(),
+        search: z.string().describe('Search query').optional()
+    }).optional()
+});
+
+/**
+ * OK
+ */
+export const zGetUsersResponse = z.array(zUser).describe('OK');

packages/openapi-ts-tests/zod/v4/__snapshots__/3.0.x/v4/validators-parameter-example/zod.gen.ts

@@ -0,0 +1,46 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { z } from 'zod';
+
+export const zUser = z.object({
+    id: z.optional(z.int()),
+    name: z.optional(z.string())
+});
+
+export const zGetUsersData = z.object({
+    body: z.optional(z.never()),
+    path: z.optional(z.never()),
+    query: z.optional(z.object({
+        sort: z.optional(z.string().meta({
+            description: 'Sort order for results',
+            example: [
+                'name,desc'
+            ]
+        })),
+        filter: z.optional(z.string().meta({
+            description: 'Filter criteria',
+            example: [
+                'status:active'
+            ]
+        })),
+        limit: z.optional(z.int().gte(1).lte(100).meta({
+            description: 'Number of results per page',
+            example: [
+                25
+            ]
+        })),
+        search: z.optional(z.string().meta({
+            description: 'Search query',
+            example: [
+                'john doe'
+            ]
+        }))
+    }))
+});
+
+/**
+ * OK
+ */
+export const zGetUsersResponse = z.array(zUser).meta({
+    description: 'OK'
+});

packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/mini/validators-metadata-global/zod.gen.ts

@@ -0,0 +1,94 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import * as z from 'zod/mini';
+
+/**
+ * User Schema
+ *
+ * A user in the system.
+ */
+export const zUser = z.object({
+    id: z.optional(z.int().register(z.globalRegistry, {
+        description: 'Unique identifier for the user',
+        example: [
+            1,
+            42,
+            999
+        ]
+    })),
+    username: z.optional(z.string().register(z.globalRegistry, {
+        description: 'The user login name',
+        example: [
+            'john_doe',
+            'jane_smith'
+        ]
+    })),
+    email: z.optional(z.email().register(z.globalRegistry, {
+        description: 'User email address',
+        example: [
+            '[email protected]',
+            '[email protected]'
+        ]
+    })),
+    age: z.optional(z.int().register(z.globalRegistry, {
+        description: 'User age in years',
+        example: [
+            25,
+            30,
+            45
+        ]
+    })),
+    role: z.optional(z.string().register(z.globalRegistry, {
+        description: 'The role of the user',
+        example: [
+            'admin',
+            'user',
+            'guest'
+        ]
+    })),
+    status: z.optional(z.enum([
+        'active',
+        'inactive',
+        'suspended'
+    ]).register(z.globalRegistry, {
+        description: 'Current status of the account',
+        example: [
+            'active'
+        ]
+    }))
+}).register(z.globalRegistry, {
+    description: 'A user in the system.'
+});
+
+/**
+ * Product
+ *
+ * A product in the catalog
+ *
+ * @deprecated
+ */
+export const zProduct = z.object({
+    sku: z.optional(z.string().check(z.regex(/^[A-Z]{3}-\d{4}$/)).register(z.globalRegistry, {
+        description: 'Product SKU code',
+        example: [
+            'ABC-1234',
+            'XYZ-9999'
+        ]
+    })),
+    price: z.optional(z.number().register(z.globalRegistry, {
+        description: 'Price in USD',
+        example: [
+            19.99,
+            49.95,
+            99.99
+        ]
+    }))
+}).register(z.globalRegistry, {
+    description: 'A product in the catalog'
+});
+
+export const zPostFooData = z.object({
+    body: z.optional(zUser),
+    path: z.optional(z.never()),
+    query: z.optional(z.never())
+});

packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/mini/validators-metadata-local/zod.gen.ts

@@ -0,0 +1,94 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import * as z from 'zod/mini';
+
+/**
+ * User Schema
+ *
+ * A user in the system.
+ */
+export const zUser = z.object({
+    id: z.optional(z.int().register(z.globalRegistry, {
+        description: 'Unique identifier for the user',
+        example: [
+            1,
+            42,
+            999
+        ]
+    })),
+    username: z.optional(z.string().register(z.globalRegistry, {
+        description: 'The user login name',
+        example: [
+            'john_doe',
+            'jane_smith'
+        ]
+    })),
+    email: z.optional(z.email().register(z.globalRegistry, {
+        description: 'User email address',
+        example: [
+            '[email protected]',
+            '[email protected]'
+        ]
+    })),
+    age: z.optional(z.int().register(z.globalRegistry, {
+        description: 'User age in years',
+        example: [
+            25,
+            30,
+            45
+        ]
+    })),
+    role: z.optional(z.string().register(z.globalRegistry, {
+        description: 'The role of the user',
+        example: [
+            'admin',
+            'user',
+            'guest'
+        ]
+    })),
+    status: z.optional(z.enum([
+        'active',
+        'inactive',
+        'suspended'
+    ]).register(z.globalRegistry, {
+        description: 'Current status of the account',
+        example: [
+            'active'
+        ]
+    }))
+}).register(z.globalRegistry, {
+    description: 'A user in the system.'
+});
+
+/**
+ * Product
+ *
+ * A product in the catalog
+ *
+ * @deprecated
+ */
+export const zProduct = z.object({
+    sku: z.optional(z.string().check(z.regex(/^[A-Z]{3}-\d{4}$/)).register(z.globalRegistry, {
+        description: 'Product SKU code',
+        example: [
+            'ABC-1234',
+            'XYZ-9999'
+        ]
+    })),
+    price: z.optional(z.number().register(z.globalRegistry, {
+        description: 'Price in USD',
+        example: [
+            19.99,
+            49.95,
+            99.99
+        ]
+    }))
+}).register(z.globalRegistry, {
+    description: 'A product in the catalog'
+});
+
+export const zPostFooData = z.object({
+    body: z.optional(zUser),
+    path: z.optional(z.never()),
+    query: z.optional(z.never())
+});

packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v3/validators-metadata-global/zod.gen.ts

@@ -0,0 +1,39 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { z } from 'zod/v3';
+
+/**
+ * User Schema
+ *
+ * A user in the system.
+ */
+export const zUser = z.object({
+    id: z.number().int().describe('Unique identifier for the user').optional(),
+    username: z.string().describe('The user login name').optional(),
+    email: z.string().email().describe('User email address').optional(),
+    age: z.number().int().describe('User age in years').optional(),
+    role: z.string().describe('The role of the user').optional(),
+    status: z.enum([
+        'active',
+        'inactive',
+        'suspended'
+    ]).describe('Current status of the account').optional()
+}).describe('A user in the system.');
+
+/**
+ * Product
+ *
+ * A product in the catalog
+ *
+ * @deprecated
+ */
+export const zProduct = z.object({
+    sku: z.string().regex(/^[A-Z]{3}-\d{4}$/).describe('Product SKU code').optional(),
+    price: z.number().describe('Price in USD').optional()
+}).describe('A product in the catalog');
+
+export const zPostFooData = z.object({
+    body: zUser.optional(),
+    path: z.never().optional(),
+    query: z.never().optional()
+});

packages/openapi-ts-tests/zod/v4/__snapshots__/3.1.x/v3/validators-metadata-local/zod.gen.ts

@@ -0,0 +1,39 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { z } from 'zod/v3';
+
+/**
+ * User Schema
+ *
+ * A user in the system.
+ */
+export const zUser = z.object({
+    id: z.number().int().describe('Unique identifier for the user').optional(),
+    username: z.string().describe('The user login name').optional(),
+    email: z.string().email().describe('User email address').optional(),
+    age: z.number().int().describe('User age in years').optional(),
+    role: z.string().describe('The role of the user').optional(),
+    status: z.enum([
+        'active',
+        'inactive',
+        'suspended'
+    ]).describe('Current status of the account').optional()
+}).describe('A user in the system.');
+
+/**
+ * Product
+ *
+ * A product in the catalog
+ *
+ * @deprecated
+ */
+export const zProduct = z.object({
+    sku: z.string().regex(/^[A-Z]{3}-\d{4}$/).describe('Product SKU code').optional(),
+    price: z.number().describe('Price in USD').optional()
+}).describe('A product in the catalog');
+
+export const zPostFooData = z.object({
+    body: zUser.optional(),
+    path: z.never().optional(),
+    query: z.never().optional()
+});