docs: OpenAPI to Contract (#1520)

Fixes: #1061

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added an "OpenAPI to Contract" guide for generating oRPC contracts
from OpenAPI specs.
* Expanded Hey API integration docs with two integration workflows and
TypeScript examples for client generation and conversion.
* Reorganized OpenAPI documentation and navigation for improved
discoverability, moving Hey API content into the OpenAPI integrations
section.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

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' },
           ],

apps/content/docs/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.

apps/content/docs/openapi/integrations/hey-api.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.