# 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 Rush](https://cloud.getrush.ai/run/add-openapi-docs/trpc/). Opens 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`

```json
{
  "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.

## 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

- [Add Optimistic Updates to a tRPC and Next.js App](https://getrush.ai/run/add-optimistic-ui/trpc/)
- [Add Prometheus Metrics to a tRPC API on Next.js](https://getrush.ai/run/add-prometheus-metrics/trpc/)
- [Add Protected Procedures to a tRPC API](https://getrush.ai/run/add-protected-procedures/trpc/)

## The same job on other stacks

- [Add OpenAPI Docs to a Vapor API](https://getrush.ai/run/add-openapi-docs/vapor/)
- [Add OpenAPI Docs to an Actix Web API](https://getrush.ai/run/add-openapi-docs/actix/)
- [Add OpenAPI Docs to an Axum API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/axum/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
