OpenAPI Reference

Raypx automatically generates an OpenAPI specification from your oRPC procedures. This provides an interactive API reference that documents all endpoints, their inputs, and their responses.

How It Works

The OpenAPI handler is configured alongside the RPC handler in src/routes/api/rpc/$.ts:

import { OpenAPIHandler } from "@orpc/openapi/fetch"
import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins"
import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4"

const apiHandler = new OpenAPIHandler(appRouter, {
  plugins: [
    new OpenAPIReferencePlugin({
      schemaConverters: [new ZodToJsonSchemaConverter()],
    }),
  ],
  interceptors: [
    onError((error) => {
      logger.error("rpc.openapi.error", { feature: "rpc", error: serializeError(error) })
    }),
  ],
})

The request flow works as follows:

1. Incoming request hits /api/rpc/$.
2. The RPC handler tries to match the request to a procedure.
3. If no match, the OpenAPI handler takes over.
4. Requests to /api/rpc/api-reference are served the interactive documentation UI.

Accessing the Reference

Navigate to the following URL in your browser:

/api/rpc/api-reference

This serves an interactive Swagger UI where you can:

• Browse all available procedures organized by router.
• View request/response schemas converted from Zod.
• See parameter types, required fields, and descriptions.

Schema Conversion

The ZodToJsonSchemaConverter converts your Zod input schemas into JSON Schema format that OpenAPI understands:

new OpenAPIReferencePlugin({
  schemaConverters: [new ZodToJsonSchemaConverter()],
})

This means every .input(z.object({...})) on your procedures is automatically documented with accurate types:

• z.string() becomes { type: "string" }
• z.enum(["a", "b"]) becomes { type: "string", enum: ["a", "b"] }
• z.boolean() becomes { type: "boolean" }
• Nested objects are converted recursively.

What Is Generated

For each procedure in your appRouter, the OpenAPI spec includes: