OpenAPI Specification

Learn how to configure metadata and generate OpenAPI documents from your oRPC contracts and routers.

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(),
  }))

INFO

For routing metadata, you can learn more in OpenAPI Routing. For input and output mapping metadata, see OpenAPI Input and Output Mapping.

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.

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, tags, spec, prefix, paramsStyle, and queryStyles are deep-merged, while operationId, summary, description, successDescription, method, path, successStatus, inputStructure, outputStructure, responseBodyHint, and requestBodyHint are overridden by the most recent call. For full merge behavior, 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 () => ([])),
}

INFO

Metadata resets to its default behavior when set to undefined in subsequent calls:

const example = os
  .meta(openapi({ tags: ['planets'] }))
  .meta(openapi({ tags: undefined }))

In this example, the final tags is undefined, so no tags are applied to example.

OpenAPI Generator

OpenAPIGenerator accepts either a contract or a router and generates an OpenAPI 3.1 document.

import { OpenAPIGenerator } from '@orpc/openapi'

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

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

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(),
  ],
})

INFO

When no matching converter is configured, OpenAPIGenerator falls back to Standard Json Schema conversion. See Standard Schema Integration for details, including how to build your own converter.

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

By default, root-level $defs generated by your converters are moved into components.schemas. Use shouldHoistDef to keep selected definitions inline:

const spec = await generator.generate(router, {
  shouldHoistDef: defName => !defName.startsWith('_'),
})

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,
  },
  customErrorResponseBodySchema: (definedErrors, status) => {
    if (status === 410) {
      return {
        type: 'object',
        properties: {
          code: { type: 'string' },
          message: { type: 'string' },
        },
        required: ['code', 'message'],
      }
    }

    // fallback to default by returning null or undefined
    return null
  },
})