diff --git a/apps/content/.vitepress/config.ts b/apps/content/.vitepress/config.ts index c75ac0929..0b750ac6f 100644 --- a/apps/content/.vitepress/config.ts +++ b/apps/content/.vitepress/config.ts @@ -107,6 +107,7 @@ export default withMermaid(defineConfig({ { text: 'Define Contract', link: '/docs/contract-first/define-contract' }, { text: 'Implement Contract', link: '/docs/contract-first/implement-contract' }, { text: 'Router to Contract', link: '/docs/contract-first/router-to-contract' }, + { text: 'OpenAPI to Contract', link: '/docs/openapi/openapi-to-contract' }, ], }, { @@ -190,7 +191,7 @@ export default withMermaid(defineConfig({ { text: 'AI SDK', link: '/docs/integrations/ai-sdk' }, { text: 'Better Auth', link: '/docs/integrations/better-auth' }, { text: 'Durable Iterator', link: '/docs/integrations/durable-iterator' }, - { text: 'Hey API', link: '/docs/integrations/hey-api' }, + { text: 'Hey API', link: '/docs/openapi/integrations/hey-api' }, { text: 'OpenTelemetry', link: '/docs/integrations/opentelemetry' }, { text: 'Pinia Colada', link: '/docs/integrations/pinia-colada' }, { text: 'Pino', link: '/docs/integrations/pino' }, @@ -261,6 +262,7 @@ export default withMermaid(defineConfig({ { text: 'OpenAPI Handler', link: '/docs/openapi/openapi-handler' }, { text: 'OpenAPI Specification', link: '/docs/openapi/openapi-specification' }, { text: 'Scalar (Swagger)', link: '/docs/openapi/scalar' }, + { text: 'OpenAPI to Contract', link: '/docs/openapi/openapi-to-contract' }, { text: 'Plugins', collapsed: true, @@ -281,6 +283,7 @@ export default withMermaid(defineConfig({ text: 'Integrations', collapsed: true, items: [ + { text: 'Hey API', link: '/docs/openapi/integrations/hey-api' }, { text: 'Implement Contract in NestJS', link: '/docs/openapi/integrations/implement-contract-in-nest' }, { text: 'tRPC', link: '/docs/openapi/integrations/trpc' }, ], diff --git a/apps/content/docs/integrations/hey-api.md b/apps/content/docs/integrations/hey-api.md deleted file mode 100644 index 9ab73a45c..000000000 --- a/apps/content/docs/integrations/hey-api.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Hey API Integration -description: Easily convert a Hey API generated client into an oRPC client to take full advantage of the oRPC ecosystem. ---- - -# Hey API Integration - -Easily convert a [Hey API](https://heyapi.dev/) generated client into an oRPC client to take full advantage of the oRPC ecosystem. - -::: warning -[Hey API](https://heyapi.dev/) is still in an unstable stage. As a result, this integration may introduce breaking changes in the future to keep up with its ongoing development. -::: - -## Installation - -::: code-group - -```sh [npm] -npm install @orpc/hey-api@latest -``` - -```sh [yarn] -yarn add @orpc/hey-api@latest -``` - -```sh [pnpm] -pnpm add @orpc/hey-api@latest -``` - -```sh [bun] -bun add @orpc/hey-api@latest -``` - -```sh [deno] -deno add npm:@orpc/hey-api@latest -``` - -::: - -## Generating an Hey API Client - -To generate a Hey API client, run the following command: - -```sh -npx @hey-api/openapi-ts \ - -i https://get.heyapi.dev/hey-api/backend \ - -o src/client -``` - -This command uses the OpenAPI spec at `https://get.heyapi.dev/hey-api/backend` and outputs the generated client into the `src/client` directory. - -::: info -For more information on Hey API, please refer to the [official documentation](https://heyapi.dev/). -::: - -## Converting to an oRPC Client - -Once the client is generated, convert it to an oRPC client using the `toORPCClient` function: - -```ts -import { experimental_toORPCClient } from '@orpc/hey-api' -import * as sdk from 'src/client/sdk.gen' - -export const client = experimental_toORPCClient(sdk) - -const { body } = await client.listPlanets() -``` - -This `client` now behaves like any standard oRPC [server-side client](/docs/client/server-side) or [client-side client](/docs/client/client-side), allowing you to use it with any oRPC-compatible library. - -## Error Handling - -Internally, oRPC passes the `throwOnError` option to the Hey API client. If the original Hey API client throws an error, oRPC will forward it as is without modification ensuring consistent error handling. diff --git a/apps/content/docs/openapi/integrations/hey-api.md b/apps/content/docs/openapi/integrations/hey-api.md new file mode 100644 index 000000000..f3e1f01a0 --- /dev/null +++ b/apps/content/docs/openapi/integrations/hey-api.md @@ -0,0 +1,44 @@ +--- +title: Hey API Integration +description: Generate oRPC contracts from OpenAPI with Hey API or adapt a Hey API generated client into an oRPC client. +--- + +# Hey API Integration + +[Hey API](https://heyapi.dev/) can be integrated with oRPC in two ways, depending on what you start with: + +- Generate an oRPC contract from an existing OpenAPI specification. +- Convert an existing Hey API generated client directly into an oRPC client. + +::: warning +The [Hey API](https://heyapi.dev/) integration is still unstable. As Hey API continues to evolve, this integration may introduce breaking changes in the future. +::: + +## Convert OpenAPI to an oRPC Contract + +If you already have an OpenAPI specification, you can use Hey API to generate an oRPC contract. See [OpenAPI to Contract](/docs/openapi/openapi-to-contract) for the complete setup and next steps. + +Once generated, you can use the contract to: + +- Implement the contract on your own server with [Implement Contract](/docs/contract-first/implement-contract). +- Create a type-safe client with [OpenAPILink](/docs/openapi/client/openapi-link). +- Use the generated contract as a reference alongside [Define Contract](/docs/contract-first/define-contract) to better understand its structure. + +## Convert a Hey API Client Directly to an oRPC Client + +If you already have a generated [Hey API client](https://heyapi.dev/openapi-ts/output) and want to use it as an oRPC client without generating a contract first, use `toORPCClient`. + +```ts +import { experimental_toORPCClient } from '@orpc/hey-api' +import * as sdk from 'src/client/sdk.gen' + +export const client = experimental_toORPCClient(sdk) + +const { body } = await client.listPlanets() +``` + +This `client` behaves like any standard oRPC [server-side client](/docs/client/server-side) or [client-side client](/docs/client/client-side), so you can use it with any oRPC-compatible library. + +### Error Handling + +Internally, oRPC passes the `throwOnError` option to the Hey API client. If the original Hey API client throws an error, oRPC forwards it as is, ensuring consistent error handling. diff --git a/apps/content/docs/openapi/openapi-to-contract.md b/apps/content/docs/openapi/openapi-to-contract.md new file mode 100644 index 000000000..705e1d69a --- /dev/null +++ b/apps/content/docs/openapi/openapi-to-contract.md @@ -0,0 +1,53 @@ +--- +title: OpenAPI to Contract +description: Generate an oRPC contract from an existing OpenAPI specification with the Hey API oRPC plugin. +--- + +# OpenAPI to Contract + +If you already have an [OpenAPI Specification](https://swagger.io/specification/), you can generate an oRPC contract with [Hey API](https://heyapi.dev/)'s `orpc` plugin instead of defining the contract manually. + +::: warning +The Hey API `orpc` plugin is currently beta and may introduce breaking changes while the integration stabilizes. +::: + +## Example + +```sh +npm install -D @hey-api/openapi-ts +``` + +```ts [openapi-ts.config.ts] +import { defineConfig } from '@hey-api/openapi-ts' + +export default defineConfig({ + input: 'https://get.heyapi.dev/hey-api/backend', + output: 'src/client', + plugins: [ + { + name: 'orpc', + validator: { + input: 'zod', + }, + }, + ], +}) +``` + +Then run: + +```sh +npx @hey-api/openapi-ts +``` + +This generates an oRPC-compatible contract from your OpenAPI specification. In this example, `zod` is used for generated input validation. + +For more details about configuration options and plugin behavior, see the [Hey API oRPC plugin documentation](https://heyapi.dev/openapi-ts/plugins/orpc). + +## What To Do Next + +Once the contract is generated, what you do next depends on how you want to use it: + +- Implement the contract on your own server with [Implement Contract](/docs/contract-first/implement-contract). +- Create a type-safe client with [OpenAPILink](/docs/openapi/client/openapi-link). +- Use the generated contract as a reference alongside [Define Contract](/docs/contract-first/define-contract) to better understand its structure.