Skip to content

openapi-handler.md

Latest commit

 

History

History
108 lines (82 loc) · 2.94 KB

openapi-handler.md

File metadata and controls

108 lines (82 loc) · 2.94 KB
title OpenAPI Handler
description Comprehensive Guide to the OpenAPIHandler in oRPC

OpenAPI Handler

The OpenAPIHandler enables communication with clients over RESTful APIs, adhering to the OpenAPI specification. It is fully compatible with OpenAPILink and the OpenAPI Specification.

Supported Data Types

OpenAPIHandler serializes and deserializes the following JavaScript types:

  • string
  • number (NaN → null)
  • boolean
  • null
  • undefined (undefined in arrays → null)
  • Date (Invalid Date → null)
  • BigInt (BigInt → string)
  • RegExp (RegExp → string)
  • URL (URL → string)
  • Record (object)
  • Array
  • Set (Set → array)
  • Map (Map → array)
  • Blob (unsupported in AsyncIteratorObject)
  • File (unsupported in AsyncIteratorObject)
  • AsyncIteratorObject (only at the root level; powers the Event Iterator)
  • ReadableStream<Uint8Array> (supported only at the root level in OpenAPIHandler; not supported by client-side OpenAPILink until v2)

::: warning If a payload contains Blob or File outside the root level, it must use multipart/form-data. In such cases, oRPC applies Bracket Notation and converts other types to strings (exclude null and undefined will not be represented). :::

:::tip You can extend the list of supported types by creating a custom serializer. :::

Installation

::: code-group

npm install @orpc/openapi@latest
yarn add @orpc/openapi@latest
pnpm add @orpc/openapi@latest
bun add @orpc/openapi@latest
deno add npm:@orpc/openapi@latest

:::

Setup and Integration

import { OpenAPIHandler } from '@orpc/openapi/fetch' // or '@orpc/server/node'
import { CORSPlugin } from '@orpc/server/plugins'
import { onError } from '@orpc/server'

const handler = new OpenAPIHandler(router, {
  plugins: [new CORSPlugin()],
  interceptors: [
    onError((error) => {
      console.error(error)
    }),
  ],
})

export default async function fetch(request: Request) {
  const { matched, response } = await handler.handle(request, {
    prefix: '/api',
    context: {} // Add initial context if needed
  })

  if (matched) {
    return response
  }

  return new Response('Not Found', { status: 404 })
}

Filtering Procedures

You can filter a procedure from matching by using the filter option:

const handler = new OpenAPIHandler(router, {
  filter: ({ contract, path }) => !contract['~orpc'].route.tags?.includes('internal'),
})

Lifecycle

The OpenAPIHandler follows the same lifecycle as the RPCHandler Lifecycle, ensuring consistent behavior across different handler types.