docs: update Zod documentation

Author: mrlubos

.changeset/famous-ducks-lay.md

@@ -0,0 +1,25 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat(zod): generate a single schema for requests
+
+### Single Zod schema per request
+
+Previously, we generated a separate schema for each endpoint parameter and request body. In v0.74.0, a single request schema is generated for the whole endpoint. It may contain a request body, parameters, and headers.
+
+```ts
+const zData = z.object({
+  body: z.object({
+    foo: z.string().optional(),
+    bar: z.union([z.number(), z.null()]).optional(),
+  }).optional(),
+  headers: z.never().optional(),
+  path: z.object({
+    baz: z.string()
+  }),
+  query: z.never().optional()
+});
+```
+
+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`.

docs/openapi-ts/migrating.md

@@ -27,6 +27,30 @@ This config option is deprecated and will be removed in favor of [clients](./cli
 
 This config option is deprecated and will be removed.
 
+## v0.74.0
+
+### Single Zod schema per request
+
+Previously, we generated a separate schema for each endpoint parameter and request body. In v0.74.0, a single request schema is generated for the whole endpoint. It may contain a request body, parameters, and headers.
+
+```ts
+const zData = z.object({
+  body: z
+    .object({
+      foo: z.string().optional(),
+      bar: z.union([z.number(), z.null()]).optional(),
+    })
+    .optional(),
+  headers: z.never().optional(),
+  path: z.object({
+    baz: z.string(),
+  }),
+  query: z.never().optional(),
+});
+```
+
+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`.
+
 ## v0.73.0
 
 ### Bundle `@hey-api/client-*` plugins

docs/openapi-ts/plugins/zod.md

@@ -26,7 +26,7 @@ Launch demo
 ## Features
 
 - seamless integration with `@hey-api/openapi-ts` ecosystem
-- Zod schemas for request payloads, parameters, and responses
+- Zod schemas for requests, responses, and reusable definitions
 
 ## Installation
 
@@ -66,6 +66,32 @@ export default {
 
 The Zod plugin will generate the following artifacts, depending on the input specification.
 
+## Requests
+
+A single request schema is generated for each endpoint. It may contain a request body, parameters, and headers.
+
+```ts
+const zData = z.object({
+  body: z
+    .object({
+      foo: z.string().optional(),
+      bar: z.union([z.number(), z.null()]).optional(),
+    })
+    .optional(),
+  headers: z.never().optional(),
+  path: z.object({
+    baz: z.string(),
+  }),
+  query: z.never().optional(),
+});
+```
+
+::: 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`.
+:::
+
+You can customize the naming and casing pattern for requests using the `requests.name` and `requests.case` options.
+
 ## Responses
 
 A single Zod schema is generated for all endpoint's responses. If the endpoint describes multiple responses, the generated schema is a union of all possible response shapes.
@@ -81,30 +107,11 @@ const zResponse = z.union([
 ]);
 ```
 
-## Request Bodies
-
-If an endpoint describes a request body, we will generate a Zod schema representing its shape.
-
-```ts
-const zData = z.object({
-  foo: z.string().optional(),
-  bar: z.union([z.number(), z.null()]).optional(),
-});
-```
-
-## Parameters
+You can customize the naming and casing pattern for responses using the `responses.name` and `responses.case` options.
 
-A separate Zod schema is generated for every request parameter.
+## Definitions
 
-```ts
-const zParameterFoo = z.number().int();
-
-const zParameterBar = z.string();
-```
-
-## Schemas
-
-A separate Zod schema is generated for every reusable schema.
+A Zod schema is generated for every reusable definition from your input.
 
 ```ts
 const zFoo = z.number().int();
@@ -114,9 +121,11 @@ const zBar = z.object({
 });
 ```
 
+You can customize the naming and casing pattern for definitions using the `definitions.name` and `definitions.case` options.
+
 ## Metadata
 
-It's often useful to associate a schema with some additional 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://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.
 
 ```js
 export default {

packages/openapi-ts-tests/test/openapi-ts.config.ts

@@ -57,7 +57,7 @@ export default defineConfig(() => {
       //   'invalid',
       //   'servers-entry.yaml',
       // ),
-      path: path.resolve(__dirname, 'spec', '3.1.x', 'type-format.yaml'),
+      path: path.resolve(__dirname, 'spec', '3.1.x', 'full.yaml'),
       // path: path.resolve(__dirname, 'spec', 'v3-transforms.json'),
       // path: 'http://localhost:4000/',
       // path: 'https://get.heyapi.dev/',
@@ -164,10 +164,7 @@ export default defineConfig(() => {
       {
         // case: 'snake_case',
         // comments: false,
-        definitions: {
-          // case: 'PascalCase',
-          // name: 'z{{name}}Yeehaw',
-        },
+        definitions: 'z{{name}}Definition',
         // exportFromIndex: true,
         // metadata: true,
         name: 'zod',