All jobs

Generate OpenAPI Docs from a tRPC Router

Yes. An agent adds OpenAPI metadata to each tRPC procedure, serves a generated openapi.json and a REST adapter next to your router, tests it, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the router before it adds a layer on top of it, because OpenAPI needs a method, a path and an input shape per procedure, and tRPC procedures declare none of those. In an app laid out like trpc/examples-next-prisma-starter, src/server/routers/_app.ts merges a healthcheck query that returns a string with postRouter from post.ts, whose three procedures take zod objects: list with an optional limit and cursor, byId with an id, and add with an optional UUID id, a title of 1 to 32 characters and text. src/server/trpc.ts builds tRPC with a superjson transformer and an unchanged error formatter, src/server/context.ts has an empty createContextInner made for tests, and src/pages/api/trpc/[trpc].ts mounts the router with createNextApiHandler. package.json pins @trpc/server and its siblings on the canary tag, zod 4, Next 15, Prisma 6 and Vitest, with pnpm typecheck, pnpm lint, a Vitest integration test in post.test.ts that calls procedures through createCaller, and a Playwright smoke test started by the test-e2e script. CI in .github/workflows/main.yml runs a Postgres service, pnpm prebuild, pnpm build, the end-to-end tests and the type check.

The agent adds trpc-to-openapi, current release 3.3.3, whose peer range takes @trpc/server 11.1 and up, zod 3.25 or 4, and zod-openapi 5.4, and checks that the installed canary resolves inside that range before going further. It gives each procedure a .meta({ openapi: { method, path, tags, summary } }): GET /posts for list, GET /posts/{id} for byId, POST /posts for add, GET /health for healthcheck. Because the library documents the response from an .output() schema, it adds one per procedure, with the post fields and the createdAt and updatedAt dates, and settles how dates serialise over REST with superjson on the router, by reading the response in a test rather than assuming.

It writes src/server/openapi.ts, which calls generateOpenApiDocument with the app title, a version and /api as the base URL, and two Next API routes: src/pages/api/openapi.json.ts, which returns that document, and src/pages/api/[...trpc].ts, which mounts createOpenApiNextHandler with the same createContext so REST calls get the same context and error formatting as tRPC calls. The existing /api/trpc/[trpc] route is untouched; the catch-all sits beside it and only answers the paths declared in the metadata.

To check it, the agent extends the Vitest suite: one test asserts the generated document has the four paths with their methods and that the add request body schema requires title and text, and one calls the REST handler for POST /posts and then GET /posts/{id} to confirm the round trip and the date format. It runs pnpm typecheck, pnpm lint, pnpm test-unit against a Postgres it starts in its sandbox, and pnpm build, and fetches /api/openapi.json from the built app to paste the first lines into the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Generate OpenAPI documentation for this tRPC router. Read package.json, src/server/trpc.ts, src/server/context.ts, src/server/routers/_app.ts, src/server/routers/post.ts, src/server/routers/post.test.ts, src/pages/api/trpc/[trpc].ts, vitest.config.ts, playwright.config.ts and .github/workflows/main.yml first. Add trpc-to-openapi and zod-openapi, confirm the installed @trpc/server satisfies the peer range, add openapi meta with method, path, tags and summary to every procedure, add output schemas, write src/server/openapi.ts that generates the document, add a Next API route that serves it at /api/openapi.json and a catch-all route that mounts the OpenAPI Next handler with the existing createContext, leaving /api/trpc untouched. Add Vitest tests for the document's paths and for a REST create-then-read round trip including the date format. Start Postgres in your sandbox, run typecheck, lint, the unit tests and the build, fetch the generated document from the built app, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes package.json, pnpm-lock.yaml, src/server/routers/_app.ts and src/server/routers/post.ts, and adds src/server/openapi.ts, src/pages/api/openapi.json.ts, src/pages/api/[...trpc].ts and a test file. Its description lists each procedure with the method and path it now has, the first lines of the generated document, the typecheck, lint, test and build output, and what a date looks like in a REST response.

The Testing workflow runs on the pull request with its Postgres service and the same steps, now including the new Vitest tests. The tRPC client, the pages and the Prisma schema are unchanged; a tRPC call behaves exactly as before, and the REST paths are a second door to the same procedures.

Before merging, a reviewer checks the paths and tags read well for whoever will consume the REST API, decides whether add should stay public over REST or move behind a protect flag once the app has authentication, and picks where the document is published, since a generated file is only useful if a client can fetch it.

Run it on every new procedure in the router

The generator runs at request time from the router, so a procedure added with .meta() appears in /api/openapi.json without another run. The run worth automating is the review: a github trigger on pull_request.opened and pull_request.synchronize starts one run per pull request, with this body's prompt replaced by one that asks the agent to stop unless the diff touches src/server/routers/, and otherwise to flag any procedure without openapi metadata or an output schema and leave a review comment. The trigger adds the pull request to the prompt after it; the agent reads it from there.

An automation run has its own max_runs_per_hour cap and is not tied to an API key, so a busy repository is throttled there rather than by a key's limit. A team that prefers a one-off instead sends this body with a request_id that is a UUID v5 of the pull request URL, so a retried call returns the run already started.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Adding OpenAPI to tRPC touches every procedure and a library whose peer ranges, transformer handling and date serialisation are easy to get subtly wrong. The agent reads the router, checks the installed versions against the library's peers, and proves the REST round trip with a test against a real database in its own sandbox, instead of leaving the first external consumer to discover the shape of a date.

The type check, the tests, the build and the fetched document stay with the run and are pasted into the pull request, so the review is about paths and naming rather than whether it works. Several services can get the same treatment at once, each from its own router.

Frequently asked questions

Does this change how my tRPC client works?

No. The existing /api/trpc/[trpc] handler, the superjson transformer and the client in src/utils/trpc.ts are untouched. The metadata on each procedure is ignored by tRPC itself; only the generator and the REST handler read it.

Why do procedures need output schemas?

The generator documents a response from the procedure's .output() schema; without one the document says nothing useful about what comes back. Adding them also makes tRPC validate responses, which catches a selector that drifts from the schema.

What about the canary tRPC version?

The library's peer range starts at @trpc/server 11.1. The agent checks the version the canary tag resolved to in pnpm-lock.yaml, and if a package manager refuses the peer it pins a released 11.x in the pull request and says so rather than forcing the install.

Can I get a Swagger or Scalar page too?

Yes, as a follow-up: both render from the same /api/openapi.json. The pull request keeps to the document and the REST handler so the review is small; a page that embeds a UI is a one-file change once the document is agreed.

More tRPC jobs

The same job on other stacks

Keep reading