Merge pull request #1430 from hey-api/fix/zod-schema-response

fix: generate response zod schemas

.changeset/fluffy-beans-clean.md

@@ -0,0 +1,30 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+fix: require sdk.transformer to use generated transformers
+
+### Added `sdk.transformer` option
+
+When generating SDKs, you now have to specify `transformer` in order to modify response data. By default, adding `@hey-api/transformers` to your plugins will only produce additional output. To preserve the previous functionality, set `sdk.transformer` to `true`.
+
+```js
+import { defaultPlugins } from '@hey-api/openapi-ts';
+
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    ...defaultPlugins,
+    {
+      dates: true,
+      name: '@hey-api/transformers',
+    },
+    {
+      name: '@hey-api/sdk',
+      transformer: true, // [!code ++]
+    },
+  ],
+};
+```

.changeset/lazy-moose-retire.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/docs': patch
+---
+
+docs: add validators page

.changeset/polite-houses-roll.md

@@ -0,0 +1,6 @@
+---
+'@hey-api/client-axios': patch
+'@hey-api/client-fetch': patch
+---
+
+fix: add responseValidator option

.changeset/shiny-birds-remain.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+feat: Zod plugin generates response schemas

.github/workflows/ci.yml

@@ -50,5 +50,5 @@ jobs:
         run: pnpm test:e2e
 
       - name: Publish previews
-        if: matrix.node-version == '21.x' && matrix.os == 'ubuntu-latest'
+        if: matrix.node-version == '22.x' && matrix.os == 'ubuntu-latest'
         run: pnpx pkg-pr-new publish --compact --pnpm './packages/*'

README.md

@@ -27,10 +27,6 @@ Love Hey API? Please consider becoming a [sponsor](https://github.com/sponsors/h
 
 Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
 
-## Migrating from OpenAPI Typescript Codegen?
+## Migration Guides
 
-Please read our [migration guide](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
-
-## Contributing
-
-Want to get involved? Please refer to the [contributing guide](https://heyapi.dev/contributing.html).
+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).

docs/.vitepress/config/en.ts

@@ -50,6 +50,17 @@ export default defineConfig({
             link: '/openapi-ts/clients',
             text: 'Clients',
           },
+          {
+            collapsed: true,
+            items: [
+              {
+                link: '/openapi-ts/validators/zod',
+                text: 'Zod',
+              },
+            ],
+            link: '/openapi-ts/validators',
+            text: 'Validators',
+          },
           {
             link: '/openapi-ts/transformers',
             text: 'Transformers',
@@ -71,10 +82,6 @@ export default defineConfig({
             link: '/openapi-ts/tanstack-query',
             text: 'TanStack Query',
           },
-          {
-            link: '/openapi-ts/zod',
-            text: 'Zod',
-          },
         ],
         text: 'Plugins',
       },

docs/index.md

@@ -67,7 +67,7 @@ features:
 
 <div class="home-list">
 
-### Migration guides
+### Migration Guides
 
 - [OpenAPI TypeScript Codegen](/openapi-ts/migrating#openapi-typescript-codegen)
 

docs/openapi-ts/clients.md

@@ -15,6 +15,7 @@ We all send HTTP requests in a slightly different way. Hey API doesn't force you
 
 - seamless integration with `@hey-api/openapi-ts` ecosystem
 - type-safe response data and errors
+- response data validation and transformation
 - access to the original request and response
 - granular request and response customization options
 - minimal learning curve thanks to extending the underlying technology

docs/openapi-ts/migrating.md

@@ -27,6 +27,33 @@ This config option is deprecated and will be removed in favor of [clients](./cli
 
 This config option is deprecated and will be removed.
 
+## v0.60.0
+
+### Added `sdk.transformer` option
+
+When generating SDKs, you now have to specify `transformer` in order to modify response data. By default, adding `@hey-api/transformers` to your plugins will only produce additional output. To preserve the previous functionality, set `sdk.transformer` to `true`.
+
+```js
+import { defaultPlugins } from '@hey-api/openapi-ts';
+
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    ...defaultPlugins,
+    {
+      dates: true,
+      name: '@hey-api/transformers',
+    },
+    {
+      name: '@hey-api/sdk',
+      transformer: true, // [!code ++]
+    },
+  ],
+};
+```
+
 ## v0.59.0
 
 ### Added `logs.level` option

docs/openapi-ts/plugins.md

@@ -26,7 +26,7 @@ These plugins help reduce boilerplate associated with third-party dependencies.
 - [`@tanstack/svelte-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
 - [`@tanstack/vue-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
 - [`fastify`](/openapi-ts/fastify) - TypeScript interface for Fastify route handlers
-- [`zod`](/openapi-ts/zod) - Zod schemas to validate your data
+- [`zod`](/openapi-ts/validators/zod) - Zod schemas to validate your data
 
 ## Community
 

docs/openapi-ts/transformers.md

@@ -1,6 +1,6 @@
 ---
 title: Transformers
-description: Learn about transforming payloads with @hey-api/openapi-ts.
+description: Learn about transforming data with @hey-api/openapi-ts.
 ---
 
 # Transformers
@@ -27,6 +27,46 @@ Transformers handle only the most common scenarios. Some of the known limitation
 
 If your data isn't being transformed as expected, we encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
 
+## Configuration
+
+To generate transformers, add `@hey-api/transformers` to your plugins.
+
+```js
+import { defaultPlugins } from '@hey-api/openapi-ts';
+
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    ...defaultPlugins,
+    '@hey-api/transformers', // [!code ++]
+  ],
+};
+```
+
+## SDKs
+
+To automatically transform response data in your SDKs, set `transformer` to `true`.
+
+```js
+import { defaultPlugins } from '@hey-api/openapi-ts';
+
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    ...defaultPlugins,
+    '@hey-api/transformers',
+    {
+      name: '@hey-api/sdk', // [!code ++]
+      transformer: true, // [!code ++]
+    },
+  ],
+};
+```
+
 ## Dates
 
 To convert date strings into `Date` objects, use the `dates` configuration option.

docs/openapi-ts/validators.md

@@ -0,0 +1,62 @@
+---
+title: Validators
+description: Learn about validating data with @hey-api/openapi-ts.
+---
+
+# Validators
+
+There are times when you cannot blindly trust the server to return the correct data. You might be working on a critical application where any mistakes would be costly, or you're simply dealing with a legacy or undocumented system.
+
+Hey API clients support validating responses so you can rest assured that you're working with the correct data.
+
+## Available Validators
+
+- [Zod](/openapi-ts/validators/zod)
+- [Ajv](https://ajv.js.org/) <span class="soon">Soon</span>
+- [Joi](https://joi.dev/) <span class="soon">Soon</span>
+- [Yup](https://github.com/jquense/yup) <span class="soon">Soon</span>
+
+If you'd like Hey API to support your validator, let us know by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
+
+## Installation
+
+There are two ways to generate validators. If you only need response validation in your SDKs, set `sdk.validator` to the desired value. For a more granular approach, add the validator to your plugins and set `sdk.validator` to `true`.
+
+::: code-group
+
+```js [sdk]
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    {
+      name: '@hey-api/sdk',
+      validator: 'zod', // [!code ++]
+    },
+  ],
+};
+```
+
+```js [validator]
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    {
+      name: '@hey-api/sdk',
+      validator: true, // [!code ++]
+    },
+    {
+      name: 'zod', // [!code ++]
+      // other options
+    },
+  ],
+};
+```
+
+:::
+
+<!--@include: ../examples.md-->
+<!--@include: ../sponsorship.md-->

docs/openapi-ts/zod.md → docs/openapi-ts/validators/zod.md

@@ -45,6 +45,28 @@ export default {
 
 You can now generate Zod artifacts. 🎉
 
+## SDKs
+
+To automatically validate response data in your SDKs, set `validator` to `true`.
+
+```js
+import { defaultPlugins } from '@hey-api/openapi-ts';
+
+export default {
+  client: '@hey-api/client-fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    ...defaultPlugins,
+    'zod',
+    {
+      name: '@hey-api/sdk', // [!code ++]
+      validator: true, // [!code ++]
+    },
+  ],
+};
+```
+
 ## Output
 
 The Zod plugin will generate the following artifacts, depending on the input specification.
@@ -53,5 +75,5 @@ The Zod plugin will generate the following artifacts, depending on the input spe
 
 More information will be provided as we finalize the plugin.
 
-<!--@include: ../examples.md-->
-<!--@include: ../sponsorship.md-->
+<!--@include: ../../examples.md-->
+<!--@include: ../../sponsorship.md-->

packages/client-axios/README.md

@@ -10,6 +10,7 @@
 
 - seamless integration with `@hey-api/openapi-ts` ecosystem
 - type-safe response data and errors
+- response data validation and transformation
 - access to the original request and response
 - granular request and response customization options
 - minimal learning curve thanks to extending the underlying technology
@@ -27,10 +28,6 @@ Love Hey API? Please consider becoming a [sponsor](https://github.com/sponsors/h
 
 Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
 
-## Migrating from OpenAPI Typescript Codegen?
+## Migration Guides
 
-Please read our [migration guide](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
-
-## Contributing
-
-Want to get involved? Please refer to the [contributing guide](https://heyapi.dev/contributing.html).
+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).

packages/client-axios/src/index.ts

@@ -64,8 +64,14 @@ export const createClient = (config: Config): Client => {
 
       let { data } = response;
 
-      if (opts.responseType === 'json' && opts.responseTransformer) {
-        data = await opts.responseTransformer(data);
+      if (opts.responseType === 'json') {
+        if (opts.responseValidator) {
+          await opts.responseValidator(data);
+        }
+
+        if (opts.responseTransformer) {
+          data = await opts.responseTransformer(data);
+        }
       }
 
       return {

packages/client-axios/src/types.ts

@@ -83,11 +83,16 @@ export interface Config<ThrowOnError extends boolean = boolean>
    */
   querySerializer?: QuerySerializer | QuerySerializerOptions;
   /**
-   * A function for transforming response data before it's returned to the
-   * caller function. This is an ideal place to post-process server data,
-   * e.g. convert date ISO strings into native Date objects.
+   * A function transforming response data before it's returned. This is useful
+   * for post-processing data, e.g. converting ISO strings into Date objects.
    */
   responseTransformer?: (data: unknown) => Promise<unknown>;
+  /**
+   * A function validating response data. This is useful if you want to ensure
+   * the response conforms to the desired shape, so it can be safely passed to
+   * the transformers and returned to the user.
+   */
+  responseValidator?: (data: unknown) => Promise<unknown>;
   /**
    * Throw an error instead of returning it in the response?
    *
@@ -97,7 +102,7 @@ export interface Config<ThrowOnError extends boolean = boolean>
 }
 
 export interface RequestOptions<
-  ThrowOnError extends boolean = false,
+  ThrowOnError extends boolean = boolean,
   Url extends string = string,
 > extends Config<ThrowOnError> {
   /**