Generate Contract from OpenAPI

Generate an oRPC contract from an existing OpenAPI specification with Hey API's orpc plugin instead of writing it by hand.

Overview

If you already have an OpenAPI specification, you can generate the contract with Hey API’s orpc plugin instead of defining it manually. Each operation in the specification becomes a procedure contract with its route, input, and output.

Example

Install Hey API:

npm install -D @hey-api/openapi-ts@next Create an `openapi-ts.config.ts` file pointing at your specification. It can be a local file or a URL: ```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/contract', plugins: [ { name: 'orpc', compatibilityVersion: '2', validator: 'zod', }, ], })

pnpm add -D @hey-api/openapi-ts@next Create an `openapi-ts.config.ts` file pointing at your specification. It can be a local file or a URL: ```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/contract', plugins: [ { name: 'orpc', compatibilityVersion: '2', validator: 'zod', }, ], })

yarn add -D @hey-api/openapi-ts@next Create an `openapi-ts.config.ts` file pointing at your specification. It can be a local file or a URL: ```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/contract', plugins: [ { name: 'orpc', compatibilityVersion: '2', validator: 'zod', }, ], })

bun add -D @hey-api/openapi-ts@next Create an `openapi-ts.config.ts` file pointing at your specification. It can be a local file or a URL: ```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/contract', plugins: [ { name: 'orpc', compatibilityVersion: '2', validator: 'zod', }, ], })

Then run:

npx @hey-api/openapi-ts

This writes orpc.gen.ts and zod.gen.ts to src/contract, with one procedure contract per operation and a contract router combining them all. In this example, zod generates the validation schemas:

import { oc } from '@orpc/contract'
import { openapi } from '@orpc/openapi'
import * as z from 'zod'

import { zAddPetBody, zAddPetResponse } from './zod.gen'

export const addPet = oc
  .meta(openapi({
    inputStructure: 'detailed',
    method: 'POST',
    path: '/pet',
    tags: ['pet'],
  }))
  .input(z.object({ body: zAddPetBody }))
  .output(zAddPetResponse)

export const contract = {
  addPet,
  // ...every other operation
}

The generated files import @orpc/contract, @orpc/openapi, and zod, so install them if you have not already:

npm install @orpc/contract@beta @orpc/openapi@beta zod

pnpm add @orpc/contract@beta @orpc/openapi@beta zod

yarn add @orpc/contract@beta @orpc/openapi@beta zod

bun add @orpc/contract@beta @orpc/openapi@beta zod

For all configuration options and plugin behavior, see the Hey API orpc plugin documentation.

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 Contract Implementation.
Call an existing OpenAPI-compliant server through a typesafe client with OpenAPI Link.