Skip to content
You are reading the v2 docs, currently in beta.V1 docs
oRPC
Esc
↑↓navigate↵open⌘Jpreview
On this page

OpenAPI Specification

Learn how to configure openapi metadata and generate OpenAPI 3.2, 3.1, or 3.0 documents from your oRPC contracts and routers, from schemas or TypeScript types.

Metadata

Use openapi metadata to control how a procedure appears in the generated OpenAPI document:

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

const getPlanet = oc
  .meta(
    openapi({
      method: 'GET',
      path: '/planets/{id}',
      operationId: 'getPlanet',
      summary: 'Get a planet',
      description: 'Returns a single planet.',
      tags: ['planets'],
      successStatus: 200,
      successDescription: 'Planet payload',
    }),
  )
  .input(
    z.object({
      id: z.string(),
    }),
  )
  .output(
    z.object({
      id: z.string(),
      name: z.string(),
    }),
  )

Customizing the Operation Object

Use spec to customize the generated operation object. If spec is an object, it replaces the generated operation object entirely. If spec is a callback, it receives the final operation object and returns an extended version. The operation object always follows OpenAPI 3.2, whatever version you generate.

const getPlanet = oc
  .meta(
    openapi({
      method: 'GET',
      path: '/planets/{id}',
      spec: (current) => ({
        ...current,
        security: [{ bearerAuth: [] }],
      }),
    }),
  )
  .input(z.object({ id: z.string() }))

Metadata Merging

When openapi is applied multiple times, most fields, such as method, path, operationId, summary, and description, are overridden by the most recent call. Only the following fields are merged:

  • tags and prefix values are concatenated in definition order.
  • paramsStyles and queryStyles are merged per parameter. The most recent style defined for a parameter wins.
  • spec values are combined: two functions are chained so the most recent one receives the result of the previous one, a function combined with an object is applied to that object, and between two objects the most recent one wins.

For implementation details, see the source code.

const router = os
  .meta(
    openapi({
      tags: ['planets'],
      spec: (current) => ({
        ...current,
        security: [{ bearerAuth: [] }],
      }),
    }),
  )
  .router({
    list: os
      .meta(openapi({ method: 'GET', summary: 'List planets', tags: ['list'] }))
      .meta(
        openapi({
          spec: {
            operationId: 'getPlanet',
            summary: 'List planets',
            responses: {
              200: {
                description: 'List of planets',
              },
            },
          },
        }),
      )
      .input(z.object({ q: z.string().optional() }))
      .handler(async () => []),
  })

These are equivalent to:

const router = {
  list: os
    .meta(
      openapi({
        method: 'GET',
        tags: ['planets', 'list'],
        summary: 'List planets',
        spec: {
          operationId: 'getPlanet',
          summary: 'List planets',
          responses: {
            200: {
              description: 'List of planets',
            },
          },
          security: [{ bearerAuth: [] }],
        },
      }),
    )
    .input(z.object({ q: z.string().optional() }))
    .handler(async () => []),
}

OpenAPI Generator

OpenAPIGenerator turns a contract or a router into an OpenAPI document.

import { OpenAPIGenerator } from '@orpc/openapi'

const generator = new OpenAPIGenerator({
  converters: [new ZodToJsonSchemaConverter()],
})

const spec = await generator.generate(router, {
  version: '3.2.0',
  base: {
    info: {
      title: 'Planet API',
      version: '1.0.0',
    },
    servers: [{ url: 'https://example.com/api' }],
  },
})

base provides the OpenAPI 3.2 document fields to start from, such as info, servers, or components. The openapi field comes from version.

OpenAPI Version

version selects the OpenAPI version, 3.2.0 by default. Any 3.0.x, 3.1.x, or 3.2.x value works.

const spec = await generator.generate(router, {
  version: '3.0.4',
})

The document is always built as OpenAPI 3.2, so base, openapi({ spec }), and every JSON schema follow 3.2. Older versions come from downgrading the whole document with @openapi-spec/downgrader, which converts what the older version can still express and removes the rest.

Json Schema Converters

OpenAPIGenerator relies on JSON Schema converters to translate your input, output, and error schemas into JSON Schemas. oRPC provides dedicated converters through the Zod, Valibot, and ArkType integrations:

import { ZodToJsonSchemaConverter } from '@orpc/zod'
import { ValibotToJsonSchemaConverter } from '@orpc/valibot'
import { ArkTypeToJsonSchemaConverter } from '@orpc/arktype'

const generator = new OpenAPIGenerator({
  converters: [
    new ZodToJsonSchemaConverter(),
    new ValibotToJsonSchemaConverter(),
    new ArkTypeToJsonSchemaConverter(),
  ],
})

Custom Serializer

If your OpenAPI Handler uses a custom serializer, configure OpenAPIGenerator with the same serializer so the generated document matches the actual formats. For details, see OpenAPI Serializer.

const handler = new OpenAPIGenerator({
  serializer: new OpenAPISerializer({
    handlers: {
      // ...custom handlers
    },
  }),
})

Filtering Procedures

Use filter to exclude procedures from the generated document:

const spec = await generator.generate(router, {
  filter: (_procedure, path) => !path.includes('internal'),
})

Hoisting $defs

Root $defs generated by your converters are moved into components.schemas. Use componentName to rename them:

const spec = await generator.generate(router, {
  componentName: (defName, defSchema) => `Api${defName}`,
})

Custom Error Response Schemas

If your OpenAPI Handler uses custom error response formats, configure OpenAPIGenerator with the same logic so the generated document matches the actual error response formats.

import { COMMON_ERROR_STATUS_MAP } from '@orpc/openapi'

const spec = await generator.generate(router, {
  errorStatusMap: {
    ...COMMON_ERROR_STATUS_MAP,
    PLANET_GONE: 410,
  },
  errorResponseBodySchema: (definedErrors, status, defaultSchema) => {
    if (status === 410) {
      return {
        type: 'object',
        properties: {
          code: { type: 'string' },
          message: { type: 'string' },
        },
        required: ['code', 'message'],
      }
    }

    return defaultSchema()
  },
})

If the handler sets errorResponseContentType, pass the same value to the generator so error responses are documented under that media type:

const spec = await generator.generate(router, {
  errorResponseContentType: 'application/problem+json',
})

Type Inference

@orpc/experimental-openapi-inference provides an OpenAPIGenerator that infers from your TypeScript types the schemas your converters cannot handle, so procedures without .output are documented too.

npm install @orpc/experimental-openapi-inference@beta
pnpm add @orpc/experimental-openapi-inference@beta
yarn add @orpc/experimental-openapi-inference@beta
bun add @orpc/experimental-openapi-inference@beta
nub add @orpc/experimental-openapi-inference@beta
aube add @orpc/experimental-openapi-inference@beta
import { OpenAPIGenerator } from '@orpc/experimental-openapi-inference'

const generator = new OpenAPIGenerator({
  converters: [new ZodToJsonSchemaConverter()],
})

const spec = await generator.generate(router, {
  source: { file: './src/router.ts', export: 'router' },
})

source.file is the file exporting the router, source.export its export name (router by default), and source.tsconfig the tsconfig whose paths resolve aliases like @/ (the nearest one by default). Other options work as in OpenAPIGenerator.

Schemas describe values as the serializer writes them, and types declared in your project become components named after them.

JSDoc

A procedure’s comment sets its summary, description, @deprecated and @tags. A type’s or property’s comment sets its description, and tags like @format, @minimum or @type integer set the matching keyword:

interface User {
  /** @type integer */
  age: number
}

Limitations

  • Types carry no runtime validation: JSDoc tags only document constraints, so keep a converter schema to validate input.
  • Custom serializer handlers are not reflected.
  • Generation throws on types the compiler cannot resolve, like an import through a missing path alias or baseUrl.

Last updated on

Was this page helpful?