skills.rest
firstaxel
firstaxelCOMMUNITY
Explore all skills by this author →
GitHub

orpc-openapi

Expose oRPC routers as spec-compliant OpenAPI HTTP APIs with routing, coercion, and spec generation.

Updated Feb 27, 2026
Search Tags:#typescript#routing#openapi#spec generation#rest api#orpc#smart coercion
One-click install
npx skills add https://github.com/firstaxel/neon --skill orpc-openapi-firstaxel
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: orpc-openapi
Source: https://github.com/firstaxel/neon/tree/main/.agents/skills/orpc-openapi
Command: npx skills add https://github.com/firstaxel/neon --skill orpc-openapi-firstaxel

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It turns an existing oRPC router into a standard REST-style OpenAPI HTTP API, so the same procedures can be served over plain HTTP, documented with an OpenAPI 3.1 spec, and consumed by any spec-compliant client without rewriting endpoints. ## Core Features & Use Cases - REST Routing on Procedures: Define HTTP methods and paths with openapi() metadata or .route, including path params, prefixes, and custom success statuses. - Serving and Coercion: Serve routers with OpenAPIHandler alongside RPCHandler, and use Smart Coercion to convert string query/path values into typed inputs. - Spec and Docs Generation: Generate an OpenAPI 3.1 document with OpenAPIGenerator and serve Scalar or Swagger UI via the OpenAPI Reference plugin. - Use Case: You have an oRPC router for a planets API and need a public REST endpoint GET /planets/{id} plus interactive docs at /spec.json—this skill wires the handler, coercion, and spec generation together. ## Quick Start Add OpenAPI routing metadata to my oRPC procedures and serve the router with OpenAPIHandler so I can call it as a REST API and view the generated spec.

Frequently Asked Questions about orpc-openapi

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I expose an oRPC procedure as a REST endpoint?▼

Attach routing metadata with `openapi({ method: 'GET', path: '/planets/{id}' })` via `.meta()`, or enable the `.route` extension by importing `@orpc/openapi/extensions/route`. Then serve the router with `OpenAPIHandler` from an adapter subpath like `@orpc/openapi/fetch`.

How do I generate an OpenAPI spec from an oRPC router?▼

Use `OpenAPIGenerator` with a schema converter such as `ZodToJsonSchemaConverter` and call `generate(router, { base: {...} })`. The `OpenAPIReferenceHandlerPlugin` serves the spec at `/spec.json` plus a Scalar or Swagger UI under the handler prefix.

Can OpenAPIHandler and RPCHandler run on the same router?▼

Yes, both handlers accept the same router. Mount them on different prefixes such as `/api` and `/rpc`, try each in turn, and return the first response whose `matched` flag is true.

Why are my query and path parameters arriving as strings?▼

Query, path, and form values always arrive as strings over HTTP. Add `SmartCoercionHandlerPlugin` from `@orpc/json-schema` with a converter like `ZodToJsonSchemaConverter` to coerce values losslessly into numbers, booleans, dates, and other schema types.

What are the limitations of bracket notation for query strings?▼

Bracket notation cannot represent empty objects or arrays, root-level arrays, or objects whose keys are all numbers, and values always arrive as strings. Use `paramsStyles` or `queryStyles` overrides for custom decoding of individual parameters.

When should I use the orpc-contract skill instead of orpc-openapi?▼

Use orpc-contract for contract-first workflows: defining contracts with `oc`, implementing them with `implement`, shipping minified contracts, or generating a contract from an existing OpenAPI spec. Use orpc-openapi for serving and consuming REST-style APIs from routers.

Related Skills

Explore More Software Engineering Skills→
ChatbotXIOChatbotXIO
601

orpc-api

Create and modify oRPC API routers, procedures, and middleware for ChatbotX.

Official
Advanced
angga30angga30

api-documenter

Author OpenAPI 3.1 and AsyncAPI specs and generate developer portals.

Community
Advanced
Quanby-IT-SolutionsQuanby-IT-Solutions
2

orpc-contracts

Define API contracts and endpoints using oRPC contracts for NestJS and Next.js.

Official
Advanced
lucasilverentandlucasilverentand
3

hono-api-design

Design Hono REST APIs with type-safe RPC and OpenAPI documentation.

Community
Advanced