Merge pull request #1490 from hey-api/docs/sections · mokkenstorm.dev/openapi-ts@c48c446

+109 -14

docs/.vitepress/config/en.ts

··· 38 38 collapsed: true, 39 39 items: [ 40 40 { 41 + link: '/openapi-ts/custom-plugin', 42 + text: 'Custom Plugin', 43 + }, 44 + ], 45 + link: '/openapi-ts/plugins', 46 + text: 'Plugins', 47 + }, 48 + { 49 + collapsed: true, 50 + items: [ 51 + { 41 52 link: '/openapi-ts/clients/fetch', 42 53 text: 'Fetch API', 43 54 }, ··· 57 68 collapsed: true, 58 69 items: [ 59 70 { 60 - link: '/openapi-ts/validators/zod', 71 + link: '/openapi-ts/plugins/zod', 61 72 text: 'Zod', 62 73 }, 74 + { 75 + link: '/openapi-ts/plugins/ajv', 76 + text: 'Ajv soon</soon>', 77 + }, 78 + { 79 + link: '/openapi-ts/plugins/arktype', 80 + text: 'Arktype soon</soon>', 81 + }, 82 + { 83 + link: '/openapi-ts/plugins/joi', 84 + text: 'Joi soon</soon>', 85 + }, 86 + { 87 + link: '/openapi-ts/plugins/superstruct', 88 + text: 'Superstruct soon</soon>', 89 + }, 90 + { 91 + link: '/openapi-ts/plugins/typebox', 92 + text: 'TypeBox soon</soon>', 93 + }, 94 + { 95 + link: '/openapi-ts/plugins/valibot', 96 + text: 'Valibot soon</soon>', 97 + }, 98 + { 99 + link: '/openapi-ts/plugins/yup', 100 + text: 'Yup soon</soon>', 101 + }, 63 102 ], 64 103 link: '/openapi-ts/validators', 65 104 text: 'Validators', ··· 68 107 link: '/openapi-ts/transformers', 69 108 text: 'Transformers', 70 109 }, 71 - ], 72 - text: 'Guides and Concepts', 73 - }, 74 - { 75 - items: [ 76 110 { 77 - link: '/openapi-ts/plugins', 78 - text: 'Introduction', 111 + collapsed: true, 112 + items: [ 113 + { 114 + link: '/openapi-ts/plugins/tanstack-query', 115 + text: 'TanStack Query', 116 + }, 117 + { 118 + link: '/openapi-ts/plugins/pinia-colada', 119 + text: 'Pinia Colada soon</soon>', 120 + }, 121 + { 122 + link: '/openapi-ts/plugins/swr', 123 + text: 'SWR soon</soon>', 124 + }, 125 + { 126 + link: '/openapi-ts/plugins/zustand', 127 + text: 'Zustand soon</soon>', 128 + }, 129 + ], 130 + link: '/openapi-ts/state-management', 131 + text: 'State Management', 79 132 }, 80 133 { 81 - link: '/openapi-ts/fastify', 82 - text: 'Fastify', 134 + collapsed: true, 135 + items: [ 136 + { 137 + link: '/openapi-ts/plugins/faker', 138 + text: 'Faker soon</soon>', 139 + }, 140 + { 141 + link: '/openapi-ts/plugins/msw', 142 + text: 'MSW soon</soon>', 143 + }, 144 + { 145 + link: '/openapi-ts/plugins/nock', 146 + text: 'Nock soon</soon>', 147 + }, 148 + { 149 + link: '/openapi-ts/plugins/supertest', 150 + text: 'Supertest soon</soon>', 151 + }, 152 + ], 153 + link: '/openapi-ts/mocks', 154 + text: 'Mocks', 83 155 }, 84 156 { 85 - link: '/openapi-ts/tanstack-query', 86 - text: 'TanStack Query', 157 + collapsed: true, 158 + items: [ 159 + { 160 + link: '/openapi-ts/plugins/fastify', 161 + text: 'Fastify', 162 + }, 163 + { 164 + link: '/openapi-ts/plugins/express', 165 + text: 'Express soon</soon>', 166 + }, 167 + { 168 + link: '/openapi-ts/plugins/hono', 169 + text: 'Hono soon</soon>', 170 + }, 171 + { 172 + link: '/openapi-ts/plugins/koa', 173 + text: 'Koa soon</soon>', 174 + }, 175 + { 176 + link: '/openapi-ts/plugins/nest', 177 + text: 'Nest soon</soon>', 178 + }, 179 + ], 180 + link: '/openapi-ts/web-frameworks', 181 + text: 'Web Frameworks', 87 182 }, 88 183 ], 89 - text: 'Plugins', 184 + text: 'Guides and Concepts', 90 185 }, 91 186 { 92 187 items: [ 93 188 { 94 189 link: '/openapi-ts/integrations', 95 - text: 'GitHub soon', 190 + text: 'GitHub soon', 96 191 }, 97 192 ], 98 193 text: 'Integrations',

+1 -1

docs/.vitepress/theme/custom.css

··· 31 31 --vp-home-hero-image-filter: blur(144px); 32 32 } 33 33 34 - .soon { 34 + [data-soon] { 35 35 background-color: var(--vp-button-brand-bg); 36 36 border-radius: 1em; 37 37 color: var(--vp-button-brand-text);

+2 -8

docs/about.md

··· 36 36 37 37 # About 38 38 39 - Hey API's objective is to provide a suite of TypeScript tools to manage API interactions. Whether you're building a front-end application, API-to-API service, or micro-frontends, we want Hey API to be your go-to resource. 40 - 41 - Typically, developers of such applications want to: 42 - 43 - - use TypeScript interfaces to model data for their APIs 44 - - send and fetch this data from server in a type-safe way 45 - - build further abstractions on top of this data 39 + Hey API is building a suite of TypeScript tools to manage API interactions. Whether you're building a web app, mobile app, or API server, we want to be part of your stack. 46 40 47 - Doing any of these steps manually quickly becomes a huge time sink as your project grows and APIs evolve. Ideally, you want to spend most time on your application. Hey API allows you to do just that. 41 + We aim to do this by offering quality code abstractions necessary to perform type-safe HTTP requests. Attempting to manage this manually quickly becomes a huge time sink as your project grows and APIs evolve. Ideally, you want to spend most time on your application. Hey API allows you to do just that. 48 42 49 43 We're constantly learning about the ways in which you use our tools. If you have any feedback, please [email us](mailto:lubos@heyapi.dev), [open an issue](https://github.com/hey-api/openapi-ts/issues), or [join a discussion](https://github.com/orgs/hey-api/discussions). 50 44

+9 -1

docs/contributing.md

··· 20 20 - use clear commit messages 21 21 - be possible to merge automatically 22 22 23 -  23 + ## Sponsors 24 + 25 + You can also contribute by becoming our [sponsor](https://github.com/sponsors/hey-api). 26 + 27 + <div class="sponsors-list"> 28 + 29 +  30 + 31 + </div>

+1 -1

docs/index.md

··· 37 37 link: /openapi-ts/plugins 38 38 linkText: Learn more 39 39 - icon: <svg class="icon-github" width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 98 98"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg> 40 - title: Integrations Soon 40 + title: Integrations Soon 41 41 details: Automatically update your code when the APIs it depends on change. Works with any codegen. 42 42 link: /openapi-ts/integrations 43 43 linkText: Find out more

+5 -3

docs/openapi-ts/clients.md

··· 21 21 - minimal learning curve thanks to extending the underlying technology 22 22 - support bundling inside the generated output 23 23 24 - ## Available Clients 24 + ## Options 25 + 26 + Hey API natively supports the following clients. 25 27 26 28 - [Fetch API](/openapi-ts/clients/fetch) 27 29 - [Axios](/openapi-ts/clients/axios) 28 30 - [Legacy](/openapi-ts/clients/legacy) 29 - - [Next.js](https://nextjs.org/) Soon 31 + - [Next.js](https://nextjs.org/) Soon 30 32 31 - If you'd like Hey API to support your client, let us know by [opening an issue](https://github.com/hey-api/openapi-ts/issues). 33 + Don't see your client? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues). 32 34 33 35  34 36

+2 -2

docs/openapi-ts/configuration.md

··· 193 193 194 194 ## Parser 195 195 196 - If you're using OpenAPI 3.0 or newer, we encourage you to try out the experimental parser. In the future it will become the default parser, but until it's been tested it's an opt-in feature. To try it out, set the `experimentalParser` flag in your configuration to `true`. 196 + If you're using OpenAPI 3.0 or newer, we encourage you to try out the experimental parser. In the future this will become the default parser, but until it's been tested it's an opt-in feature. To try it out, set the `experimentalParser` flag in your configuration to `true`. 197 197 198 198 ::: code-group 199 199 ··· 212 212 213 213 ::: 214 214 215 - The experimental parser produces a cleaner output while being faster than the legacy parser. It also supports features such as [Filters](#filters) and more will be added in the future. 215 + The experimental parser produces a cleaner output while being faster than the legacy parser. It also supports features such as [Filters](#filters) and more are being added. 216 216 217 217 The legacy parser will be used with the [legacy clients](/openapi-ts/clients/legacy) regardless of the `experimentalParser` flag value. However, it's unlikely to receive any further updates. 218 218

+200

docs/openapi-ts/custom-plugin.md

··· 1 + --- 2 + title: Custom Plugin 3 + description: Learn how to create your own Hey API plugin. 4 + --- 5 + 6 + # Custom Plugin 7 + 8 + ::: warning 9 + Plugin API is in development. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues). 10 + ::: 11 + 12 + You may need to write your own plugin if the available plugins do not suit your needs or you're working on a proprietary use case. This can be easily achieved using the Plugin API. But don't take our word for it – all Hey API plugins are written this way! 13 + 14 + ## File Structure 15 + 16 + We recommend following the design pattern of the native plugins. You can browse the code on [GitHub](https://github.com/hey-api/openapi-ts/tree/main/packages/openapi-ts/src/plugins) as you follow this tutorial. First, create a `my-plugin` folder for your plugin files. Inside, create a barrel file `index.ts` exporting the plugin. 17 + 18 + ::: code-group 19 + 20 + ```ts [index.ts] 21 + export { defaultConfig, defineConfig } from './config'; 22 + export type { Config } from './types'; 23 + ``` 24 + 25 + ::: 26 + 27 + ## TypeScript 28 + 29 + `index.ts` references two files, so we need to create them. `types.d.ts` contains the TypeScript interface for your plugin options. It must have the reserved `name` and `output` fields, everything else will become user-configurable options. 30 + 31 + ::: code-group 32 + 33 + ```ts [types.d.ts] 34 + export interface Config { 35 + /** 36 + * Plugin name. Must be unique. 37 + */ 38 + name: 'my-plugin'; 39 + /** 40 + * Name of the generated file. 41 + * 42 + * @default 'my-plugin' 43 + */ 44 + output?: string; 45 + /** 46 + * User-configurable option for your plugin. 47 + * 48 + * @default false 49 + */ 50 + myOption?: boolean; 51 + } 52 + ``` 53 + 54 + ::: 55 + 56 + ## Configuration 57 + 58 + ::: tip 59 + Reserved fields are prefixed with an underscore and are not exposed to the user. 60 + ::: 61 + 62 + `config.ts` contains the runtime configuration for your plugin. It must implement the `Config` interface we created above and define `_handler()` and `_handlerLegacy()` functions from the `Plugin.Config` interface. 63 + 64 + ::: code-group 65 + 66 + ```ts [config.ts] 67 + import type { Plugin } from '@hey-api/openapi-ts'; 68 + 69 + import { handler } from './plugin'; 70 + import type { Config } from './types'; 71 + 72 + export const defaultConfig: Plugin.Config<Config> = { 73 + _dependencies: ['@hey-api/typescript'], 74 + _handler: handler, 75 + _handlerLegacy: () => {}, 76 + myOption: false, // implements default value from types 77 + name: 'my-plugin', 78 + output: 'my-plugin', 79 + }; 80 + 81 + /** 82 + * Type helper for `my-plugin` plugin, returns {@link Plugin.Config} object 83 + */ 84 + export const defineConfig: Plugin.DefineConfig<Config> = (config) => ({ 85 + ...defaultConfig, 86 + ...config, 87 + }); 88 + ``` 89 + 90 + ::: 91 + 92 + In the file above, we define a `my-plugin` plugin which will generate a `my-plugin.gen.ts` file. We also demonstrate declaring `@hey-api/typescript` as a dependency for our plugin, so we can safely import artifacts from `types.gen.ts`. 93 + 94 + By default, your plugin output won't be re-exported from the `index.ts` file. To enable this feature, add `exportFromIndex: true` to your `config.ts` file. 95 + 96 + ::: warning 97 + Re-exporting your plugin from `index.ts` may result in broken output due to naming conflicts. Ensure your exported identifiers are unique. 98 + ::: 99 + 100 + ## Handler 101 + 102 + ::: warning 103 + To use this feature, you must opt in to the [experimental parser](/openapi-ts/configuration#parser). 104 + ::: 105 + 106 + Notice we defined `_handler` in our `config.ts` file. This method is responsible for generating the actual output. We recommend implementing it in `plugin.ts`. 107 + 108 + ::: code-group 109 + 110 + ```ts [plugin.ts] 111 + import type { Plugin } from '@hey-api/openapi-ts'; 112 + 113 + import type { Config } from './types'; 114 + 115 + export const handler: Plugin.Handler<Config> = ({ context, plugin }) => { 116 + // create an output file. it will not be 117 + // generated until it contains nodes 118 + const file = context.createFile({ 119 + id: plugin.name, 120 + path: plugin.output, 121 + }); 122 + 123 + context.subscribe('before', () => { 124 + // do something before parsing the input 125 + }); 126 + 127 + context.subscribe('operation', ({ operation }) => { 128 + // do something with the operation model 129 + }); 130 + 131 + context.subscribe('schema', ({ operation }) => { 132 + // do something with the schema model 133 + }); 134 + 135 + context.subscribe('after', () => { 136 + // do something after parsing the input 137 + }); 138 + 139 + // we're using the TypeScript Compiler API 140 + const stringLiteral = ts.factory.createStringLiteral('Hello, world!'); 141 + const variableDeclaration = ts.factory.createVariableDeclaration( 142 + 'foo', 143 + undefined, 144 + undefined, 145 + stringLiteral, 146 + ); 147 + const node = ts.factory.createVariableStatement( 148 + [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], 149 + ts.factory.createVariableDeclarationList( 150 + [variableDeclaration], 151 + ts.NodeFlags.Const, 152 + ), 153 + ); 154 + 155 + // add a node to our file 156 + file.add(node); 157 + }; 158 + ``` 159 + 160 + ::: 161 + 162 + ### Legacy 163 + 164 + Notice we defined `_handlerLegacy` in our `config.ts` file. This method is responsible for generating the actual output when using the legacy parser. We do not recommend implementing this method unless you must use the legacy parser. You can use one of our [`plugin-legacy.ts`](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/%40hey-api/typescript/plugin-legacy.ts) files as an inspiration for potential implementation. 165 + 166 + ## Usage 167 + 168 + Once we're satisfied with our plugin, we can register it in the [configuration](/openapi-ts/configuration) file. 169 + 170 + ```js 171 + import { defineConfig } from 'path/to/my-plugin'; 172 + 173 + export default { 174 + client: '@hey-api/client-fetch', 175 + input: 'path/to/openapi.json', 176 + output: 'src/client', 177 + plugins: [ 178 + defineConfig({ 179 + myOption: true, 180 + }), 181 + ], 182 + }; 183 + ``` 184 + 185 + ## Output 186 + 187 + Putting all of this together will generate the following `my-plugin.gen.ts` file. 188 + 189 + ::: code-group 190 + 191 + ```ts [my-plugin.gen.ts] 192 + export const foo = 'Hello, world!'; 193 + ``` 194 + 195 + ::: 196 + 197 + Congratulations! You've successfully created your own plugin! :tada: 198 + 199 +  200 +

+3 -5

docs/openapi-ts/fastify.md docs/openapi-ts/plugins/fastify.md

··· 27 27 To use this feature, you must opt in to the [experimental parser](/openapi-ts/configuration#parser). 28 28 ::: 29 29 30 - Ensure you have already [configured](/openapi-ts/get-started) `@hey-api/openapi-ts`. Update your configuration to use the Fastify plugin. 30 + Assuming you have already created a [configuration](/openapi-ts/get-started) file, simply add `fastify` to your plugins and you'll be ready to generate Fastify artifacts. :tada: 31 31 32 32 ```js 33 33 import { defaultPlugins } from '@hey-api/openapi-ts'; ··· 43 43 ], 44 44 }; 45 45 ``` 46 - 47 - You can now generate Fastify artifacts. 🎉 48 46 49 47 ## Output 50 48 ··· 73 71 fastify.register(glue, { serviceHandlers }); 74 72 ``` 75 73 76 -  77 -  74 +  75 +

+1 -1

docs/openapi-ts/integrations.md

··· 3 3 description: Automate your client generation. 4 4 --- 5 5 6 - # Integrations Soon 6 + # Integrations Soon 7 7 8 8 ::: warning 9 9 GitHub integration is not publicly available yet. We are gathering feedback from beta testers to ensure the final product meets our quality standards. To express your interest in joining the beta test, please open an issue on [GitHub](https://github.com/hey-api/upload-openapi-spec/issues).

+22

docs/openapi-ts/mocks.md

··· 1 + --- 2 + title: Mocks 3 + description: Learn about mocking HTTP servers with @hey-api/openapi-ts. 4 + --- 5 + 6 + # Mocks 7 + 8 + Realistic mock data is an important component of every robust development process, testing strategy, and product presentation. 9 + 10 + ## Options 11 + 12 + Hey API natively supports the following mocking frameworks. 13 + 14 + - [Faker](/openapi-ts/plugins/faker) Soon 15 + - [MSW](/openapi-ts/plugins/msw) Soon 16 + - [Nock](/openapi-ts/plugins/nock) Soon 17 + - [Supertest](/openapi-ts/plugins/supertest) Soon 18 + 19 + Don't see your framework? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues). 20 + 21 +  22 +

+32 -139

docs/openapi-ts/plugins.md

··· 5 5 6 6 # Plugins 7 7 8 - Every generated file in your output is created by a plugin. You already learned about the default plugins in [Output](/openapi-ts/output). This page contains all native plugins and shows you how to create your own. 8 + Every generated file in your output is created by a plugin. You already learned about the default plugins in [Output](/openapi-ts/output). This page contains all native and selected community plugins. 9 9 10 10 ## Hey API 11 11 12 - Apart from being responsible for the default output, Hey API plugins are the foundation for other plugins. Instead of creating their own primitives, other plugins can reuse the artifacts from Hey API plugins. This results in smaller output and a better user experience. 12 + Apart from being responsible for the default output, Hey API plugins are the foundation for other plugins. Instead of creating their own primitives, other plugins can reuse the artifacts from Hey API plugins. This results in a smaller output size and a better user experience. 13 13 14 14 - `@hey-api/schemas` - export OpenAPI definitions as JavaScript objects 15 15 - `@hey-api/sdk` - robust and polished SDKs ··· 20 20 21 21 These plugins help reduce boilerplate associated with third-party dependencies. Hey API natively supports the most popular packages. Please open an issue on [GitHub](https://github.com/hey-api/openapi-ts/issues) if you'd like us to support your favorite package. 22 22 23 - - [`@tanstack/angular-query-experimental`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys 24 - - [`@tanstack/react-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys 25 - - [`@tanstack/solid-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys 26 - - [`@tanstack/svelte-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys 27 - - [`@tanstack/vue-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys 28 - - [`fastify`](/openapi-ts/fastify) - TypeScript interface for Fastify route handlers 29 - - [`zod`](/openapi-ts/validators/zod) - Zod schemas to validate your data 23 + - [`@tanstack/angular-query-experimental`](/openapi-ts/plugins/tanstack-query) 24 + - [`@tanstack/react-query`](/openapi-ts/plugins/tanstack-query) 25 + - [`@tanstack/solid-query`](/openapi-ts/plugins/tanstack-query) 26 + - [`@tanstack/svelte-query`](/openapi-ts/plugins/tanstack-query) 27 + - [`@tanstack/vue-query`](/openapi-ts/plugins/tanstack-query) 28 + - [`fastify`](/openapi-ts/plugins/fastify) 29 + - [`zod`](/openapi-ts/plugins/zod) 30 30 31 - ## Community 32 - 33 - Featured community plugins. 34 - 35 - - [add plugin](https://github.com/hey-api/openapi-ts/pulls) 36 - 37 - ## Custom 38 - 39 - ::: warning 40 - Plugin API is in development. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues). 41 - ::: 42 - 43 - If the existing plugins do not handle your use case or you're working with proprietary packages, you might want to create your own plugin. 44 - 45 - ### Configuration 46 - 47 - We recommend following the design pattern of the native plugins. First, create a `my-plugin` folder for your plugin files. Inside, create a barrel file `index.ts` exporting the plugin's API. 48 - 49 - ::: code-group 50 - 51 - ```ts [index.ts] 52 - export { defaultConfig, defineConfig } from './config'; 53 - export type { Config } from './types'; 54 - ``` 31 + ## Upcoming 55 32 56 - ::: 33 + The following plugins are planned but not in development yet. You can help us prioritize them by voting on [GitHub](https://github.com/hey-api/openapi-ts/labels/RSVP%20%F0%9F%91%8D%F0%9F%91%8E). 57 34 58 - `index.ts` references 2 files, so we need to create them. `types.d.ts` contains the TypeScript interface for your plugin's options. It must have the `name` and `output` fields, everything else will become your plugin's configuration options. 35 + - [Ajv](/openapi-ts/plugins/ajv) Soon 36 + - [Arktype](/openapi-ts/plugins/arktype) Soon 37 + - [Express](/openapi-ts/plugins/express) Soon 38 + - [Faker](/openapi-ts/plugins/faker) Soon 39 + - [Hono](/openapi-ts/plugins/hono) Soon 40 + - [Joi](/openapi-ts/plugins/joi) Soon 41 + - [Koa](/openapi-ts/plugins/koa) Soon 42 + - [MSW](/openapi-ts/plugins/msw) Soon 43 + - [Nest](/openapi-ts/plugins/nest) Soon 44 + - [Nock](/openapi-ts/plugins/nock) Soon 45 + - [Pinia Colada](/openapi-ts/plugins/pinia-colada) Soon 46 + - [Superstruct](/openapi-ts/plugins/superstruct) Soon 47 + - [Supertest](/openapi-ts/plugins/supertest) Soon 48 + - [SWR](/openapi-ts/plugins/swr) Soon 49 + - [TypeBox](/openapi-ts/plugins/typebox) Soon 50 + - [Valibot](/openapi-ts/plugins/valibot) Soon 51 + - [Yup](/openapi-ts/plugins/yup) Soon 52 + - [Zustand](/openapi-ts/plugins/zustand) Soon 59 53 60 - ::: code-group 54 + ## Community 61 55 62 - ```ts [types.d.ts] 63 - export interface Config { 64 - /** 65 - * Plugin name. Must be unique. 66 - */ 67 - name: 'my-plugin'; 68 - /** 69 - * Name of the generated file. 70 - * 71 - * @default 'my-plugin' 72 - */ 73 - output?: string; 74 - /** 75 - * A custom option for your plugin. 76 - */ 77 - myOption?: boolean; 78 - } 79 - ``` 56 + Featured community plugins. 80 57 81 - ::: 82 - 83 - `config.ts` contains the runtime configuration for your plugin. It must implement the `Config` interface from `types.d.ts` and additional plugin metadata defined in the `Plugin.Config` interface. 84 - 85 - ::: code-group 86 - 87 - ```ts [config.ts] 88 - import type { Plugin } from '@hey-api/openapi-ts'; 89 - 90 - import { handler } from './plugin'; 91 - import type { Config } from './types'; 92 - 93 - export const defaultConfig: Plugin.Config<Config> = { 94 - _dependencies: ['@hey-api/typescript'], 95 - _handler: handler, 96 - _handlerLegacy: () => {}, 97 - name: 'my-plugin', 98 - output: 'my-plugin', 99 - }; 100 - 101 - /** 102 - * Type helper for `my-plugin` plugin, returns {@link Plugin.Config} object 103 - */ 104 - export const defineConfig: Plugin.DefineConfig<Config> = (config) => ({ 105 - ...defaultConfig, 106 - ...config, 107 - }); 108 - ``` 109 - 110 - ::: 111 - 112 - In the `config.ts` above, we define a `my-plugin` plugin which will generate a `my-plugin.gen.ts` output file. We also demonstrate declaring `@hey-api/typescript` as a dependency for our plugin, so we can safely import artifacts from `types.gen.ts`. 113 - 114 - Lastly, we define the `_handler` method which will be responsible for generating our custom output. We just need to create the remaining `plugin.ts` file. 115 - 116 - ::: code-group 117 - 118 - ```ts [plugin.ts] 119 - import type { Plugin } from '@hey-api/openapi-ts'; 120 - 121 - import type { Config } from './types'; 122 - 123 - export const handler: Plugin.Handler<Config> = ({ context, plugin }) => { 124 - // create a file for our output 125 - const file = context.createFile({ 126 - id: plugin.name, 127 - path: plugin.output, 128 - }); 129 - 130 - context.subscribe('before', () => { 131 - // do something before parsing the input 132 - }); 133 - 134 - context.subscribe('operation', ({ operation }) => { 135 - // do something with the operation model 136 - }); 137 - 138 - context.subscribe('schema', ({ operation }) => { 139 - // do something with the schema model 140 - }); 141 - 142 - context.subscribe('after', () => { 143 - // do something after parsing the input 144 - }); 145 - }; 146 - ``` 147 - 148 - ::: 149 - 150 - And that's it! We can now register our plugin in the Hey API configuration. 151 - 152 - ```js 153 - import { defineConfig } from './src/my-plugin'; 154 - 155 - export default { 156 - client: '@hey-api/client-fetch', 157 - input: 'path/to/openapi.json', 158 - output: 'src/client', 159 - plugins: [ 160 - defineConfig({ 161 - myOption: true, 162 - }), 163 - ], 164 - }; 165 - ``` 58 + - [add plugin](https://github.com/hey-api/openapi-ts/pulls) 166 59 167 60  168 61

+14

docs/openapi-ts/plugins/ajv.md

··· 1 + --- 2 + title: Ajv 3 + description: Ajv plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Ajv soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1476). 10 + ::: 11 + 12 + [Ajv](https://ajv.js.org/) is the fastest JSON validator for Node.js and browser. 13 + 14 +

+14

docs/openapi-ts/plugins/arktype.md

··· 1 + --- 2 + title: Arktype 3 + description: Arktype plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Arktype soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1473). 10 + ::: 11 + 12 + [Arktype](https://arktype.io/) is a TypeScript's 1:1 validator, optimized from editor to runtime. 13 + 14 +

+14

docs/openapi-ts/plugins/express.md

··· 1 + --- 2 + title: Express 3 + description: Express plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Express soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1484). 10 + ::: 11 + 12 + [Express](https://expressjs.com/) is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications. 13 + 14 +

+14

docs/openapi-ts/plugins/faker.md

··· 1 + --- 2 + title: Faker 3 + description: Faker plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Faker soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1485). 10 + ::: 11 + 12 + [Faker](https://fakerjs.dev/) is a popular library that generates fake (but reasonable) data that can be used for things such as unit testing, performance testing, building demos, and working without a completed backend. 13 + 14 +

+14

docs/openapi-ts/plugins/hono.md

··· 1 + --- 2 + title: Hono 3 + description: Hono plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Hono soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1483). 10 + ::: 11 + 12 + [Hono](https://hono.dev/) is a small, simple, and ultrafast web framework built on Web Standards. It works on any JavaScript runtime: Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, Netlify, AWS Lambda, Lambda@Edge, and Node.js. 13 + 14 +

+14

docs/openapi-ts/plugins/joi.md

··· 1 + --- 2 + title: Joi 3 + description: Joi plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Joi soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1477). 10 + ::: 11 + 12 + [Joi](https://joi.dev/) is the most powerful schema description language and data validator for JavaScript. 13 + 14 +

+14

docs/openapi-ts/plugins/koa.md

··· 1 + --- 2 + title: Koa 3 + description: Koa plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Koa soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1482). 10 + ::: 11 + 12 + [Koa](https://koajs.com/) is a new web framework designed by the team behind Express, which aims to be a smaller, more expressive, and more robust foundation for web applications and APIs. 13 + 14 +

+14

docs/openapi-ts/plugins/msw.md

··· 1 + --- 2 + title: MSW 3 + description: MSW plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # MSW soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1486). 10 + ::: 11 + 12 + [MSW](https://mswjs.io/) is an API mocking library that allows you to write client-agnostic mocks and reuse them across any frameworks, tools, and environments. 13 + 14 +

+14

docs/openapi-ts/plugins/nest.md

··· 1 + --- 2 + title: Nest 3 + description: Nest plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Nest soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1481). 10 + ::: 11 + 12 + [Nest](https://nestjs.com/) is a progressive Node.js framework for building efficient, reliable and scalable server-side applications. 13 + 14 +

+14

docs/openapi-ts/plugins/nock.md

··· 1 + --- 2 + title: Nock 3 + description: Nock plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Nock soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1487). 10 + ::: 11 + 12 + [Nock](https://github.com/nock/nock) is an HTTP server mocking and expectations library for Node.js. 13 + 14 +

+14

docs/openapi-ts/plugins/pinia-colada.md

··· 1 + --- 2 + title: Pinia Colada 3 + description: Pinia Colada plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Pinia Colada soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1242). 10 + ::: 11 + 12 + [Pinia Colada](https://pinia-colada.esm.dev/) is the data fetching layer for Pinia. 13 + 14 +

+14

docs/openapi-ts/plugins/superstruct.md

··· 1 + --- 2 + title: Superstruct 3 + description: Superstruct plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Superstruct soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1489). 10 + ::: 11 + 12 + [Superstruct](https://docs.superstructjs.org/) makes it easy to define interfaces and then validate JavaScript data against them. 13 + 14 +

+14

docs/openapi-ts/plugins/supertest.md

··· 1 + --- 2 + title: Supertest 3 + description: Supertest plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Supertest soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1488). 10 + ::: 11 + 12 + [Supertest](https://github.com/ladjs/supertest) is a super-agent driven library for testing node.js HTTP servers using a fluent API. 13 + 14 +

+14

docs/openapi-ts/plugins/swr.md

··· 1 + --- 2 + title: SWR 3 + description: SWR plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # SWR soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1479). 10 + ::: 11 + 12 + [SWR](https://swr.vercel.app/) is a strategy to first return the data from cache (stale), then send the fetch request (revalidate), and finally come with the up-to-date data. 13 + 14 +

+14

docs/openapi-ts/plugins/typebox.md

··· 1 + --- 2 + title: TypeBox 3 + description: TypeBox plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # TypeBox soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1475). 10 + ::: 11 + 12 + [TypeBox](https://github.com/sinclairzx81/typebox) is a JSON Schema type builder with static type resolution for TypeScript. 13 + 14 +

+14

docs/openapi-ts/plugins/valibot.md

··· 1 + --- 2 + title: Valibot 3 + description: Valibot plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Valibot soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1474). 10 + ::: 11 + 12 + [Valibot](https://valibot.dev/) is the open source schema library for TypeScript with bundle size, type safety and developer experience in mind. 13 + 14 +

+14

docs/openapi-ts/plugins/yup.md

··· 1 + --- 2 + title: Yup 3 + description: Yup plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Yup soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1478). 10 + ::: 11 + 12 + [Yup](https://github.com/jquense/yup) is a schema builder for runtime value parsing and validation. 13 + 14 +

+14

docs/openapi-ts/plugins/zustand.md

··· 1 + --- 2 + title: Zustand 3 + description: Zustand plugin for Hey API. Compatible with all our features. 4 + --- 5 + 6 + # Zustand soon 7 + 8 + ::: warning 9 + This feature isn't in development yet. Help us prioritize it by voting on [GitHub](https://github.com/hey-api/openapi-ts/issues/1480). 10 + ::: 11 + 12 + [Zustand](https://zustand-demo.pmnd.rs/) is a small, fast, and scalable bearbones state management solution. 13 + 14 +

+22

docs/openapi-ts/state-management.md

··· 1 + --- 2 + title: State Management 3 + description: Learn about handling state with @hey-api/openapi-ts. 4 + --- 5 + 6 + # State Management 7 + 8 + Any reasonably large application will have to deal with state management at some point. State-related code is often one of the biggest boilerplates in your codebase. Well, at least until you start using our state management plugins. 9 + 10 + ## Options 11 + 12 + Hey API natively supports the following state managers. 13 + 14 + - [TanStack Query](/openapi-ts/plugins/tanstack-query) 15 + - [Pinia Colada](/openapi-ts/plugins/pinia-colada) Soon 16 + - [SWR](/openapi-ts/plugins/swr) Soon 17 + - [Zustand](/openapi-ts/plugins/zustand) Soon 18 + 19 + Don't see your state manager? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues). 20 + 21 +  22 +

+4 -6

docs/openapi-ts/tanstack-query.md docs/openapi-ts/plugins/tanstack-query.md

··· 4 4 --- 5 5 6 6 <script setup> 7 - import { embedProject } from '../embed' 7 + import { embedProject } from '../../embed' 8 8 </script> 9 9 10 10 # TanStack Query ··· 28 28 29 29 ## Installation 30 30 31 - Ensure you have already [configured](/openapi-ts/get-started) `@hey-api/openapi-ts`. Update your configuration to use the TanStack Query plugin. 31 + Assuming you have already created a [configuration](/openapi-ts/get-started) file, simply add TanStack Query to your plugins and you'll be ready to generate TanStack Query artifacts. :tada: 32 32 33 33 ::: code-group 34 34 ··· 104 104 105 105 ::: 106 106 107 - You can now generate TanStack Query artifacts. 🎉 108 - 109 107 ## Output 110 108 111 109 The TanStack Query plugin will optionally generate the following artifacts, depending on the input specification. ··· 181 179 }); 182 180 ``` 183 181 184 -  185 -  182 +  183 +

+3 -3

docs/openapi-ts/transformers.md

··· 27 27 28 28 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). 29 29 30 - ## Configuration 30 + ## Installation 31 31 32 - To generate transformers, add `@hey-api/transformers` to your plugins. 32 + Assuming you have already created a [configuration](/openapi-ts/get-started) file, simply add `@hey-api/transformers` to your plugins and you'll be ready to generate transformers. :tada: 33 33 34 34 ```js 35 35 import { defaultPlugins } from '@hey-api/openapi-ts'; ··· 47 47 48 48 ## SDKs 49 49 50 - To automatically transform response data in your SDKs, set `transformer` to `true`. 50 + To automatically transform response data in your SDKs, set `sdk.transformer` to `true`. 51 51 52 52 ```js 53 53 import { defaultPlugins } from '@hey-api/openapi-ts';

+13 -8

docs/openapi-ts/validators.md

··· 7 7 8 8 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. 9 9 10 - Hey API clients support validating responses so you can rest assured that you're working with the correct data. 10 + Whatever your reason to use validators might be, you can rest assured that you're working with the correct data. 11 11 12 - ## Available Validators 12 + ## Options 13 + 14 + Hey API natively supports the following validators. 13 15 14 - - [Zod](/openapi-ts/validators/zod) 15 - - [Ajv](https://ajv.js.org/) Soon 16 - - [Joi](https://joi.dev/) Soon 17 - - [Yup](https://github.com/jquense/yup) Soon 16 + - [Zod](/openapi-ts/plugins/zod) 17 + - [Ajv](/openapi-ts/plugins/ajv) Soon 18 + - [Arktype](/openapi-ts/plugins/arktype) Soon 19 + - [Joi](/openapi-ts/plugins/joi) Soon 20 + - [TypeBox](/openapi-ts/plugins/typebox) Soon 21 + - [Valibot](/openapi-ts/plugins/valibot) Soon 22 + - [Yup](/openapi-ts/plugins/yup) Soon 18 23 19 - 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). 24 + Don't see your validator? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues). 20 25 21 26 ## Installation 22 27 23 - 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`. 28 + 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 your validator to plugins and set `sdk.validator` to `true`. 24 29 25 30 ::: code-group 26 31

+3 -5

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

··· 6 6 # Zod 7 7 8 8 ::: warning 9 - Zod plugin is in development. You can follow the updates and provide feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues/876). 9 + This feature is in development! :tada: Try it out and provide feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues/876). 10 10 ::: 11 11 12 12 [Zod](https://zod.dev/) is a TypeScript-first schema validation library with static type inference. ··· 26 26 To use this feature, you must opt in to the [experimental parser](/openapi-ts/configuration#parser). 27 27 ::: 28 28 29 - Ensure you have already [configured](/openapi-ts/get-started) `@hey-api/openapi-ts`. Update your configuration to use the Zod plugin. 29 + Assuming you have already created a [configuration](/openapi-ts/get-started) file, simply add `zod` to your plugins and you'll be ready to generate Zod artifacts. :tada: 30 30 31 31 ```js 32 32 import { defaultPlugins } from '@hey-api/openapi-ts'; ··· 43 43 }; 44 44 ``` 45 45 46 - You can now generate Zod artifacts. 🎉 47 - 48 46 ## SDKs 49 47 50 - To automatically validate response data in your SDKs, set `validator` to `true`. 48 + To automatically validate response data in your SDKs, set `sdk.validator` to `true`. 51 49 52 50 ```js 53 51 import { defaultPlugins } from '@hey-api/openapi-ts';

+23

docs/openapi-ts/web-frameworks.md

··· 1 + --- 2 + title: Web Frameworks 3 + description: Learn about generating web framework code with @hey-api/openapi-ts. 4 + --- 5 + 6 + # Web Frameworks 7 + 8 + There are two approaches to developing APIs: code-first, where you start with the code, or spec-first, where you begin with the specification. If you use the latter, you can ensure your APIs adhere to the specification with our web framework plugins. 9 + 10 + ## Options 11 + 12 + Hey API natively supports the following frameworks. 13 + 14 + - [Fastify](/openapi-ts/plugins/fastify) 15 + - [Express](/openapi-ts/plugins/express) Soon 16 + - [Hono](/openapi-ts/plugins/hono) Soon 17 + - [Koa](/openapi-ts/plugins/koa) Soon 18 + - [Nest](/openapi-ts/plugins/nest) Soon 19 + 20 + Don't see your framework? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues). 21 + 22 +  23 +