\n\n\n## **[Swagger](https://swagger.io/specification/) integration for [tRPC](https://trpc.io/)** \n\n- Easy REST endpoints for your tRPC procedures.\n- Perfect for incremental adoption.\n- OpenAPI version 3.0.3.\n\n## Fork Notice\nThe original repo [trpc-openapi](https://github.com/James/trpc-openapi) no longer appears to be maintained. \nThe goal of this fork is to add more control for error responses, support more frameworks, and support the new procedure types in @trpc v11.x.x.\nPRs Are welcome\n\n\n## TRPC v10\nfor those looking for tRPC v10 - please use version ^1.2.8\n\n## TRPC v11\nfor those looking for tRPC v11 - please use version ^2.0.0\n\n\n## Local Examples\nIf you've pulled the repo. you can run any of the example projects by first running these 2 commands:\n```\nyarn install\n```\n```\nyarn build\n```\nThen select a workspace\n```bash\nyarn workspace with-[WORKSPACE_NAME] run dev\n```\nErgo\n```yaml\nyarn workspace with-nextjs-app run dev\nyarn workspace with-nextjs-app run build\n```\n\n## Usage\n\n**1. Install `trpc-swagger`**\n\n```bash\nnpm install trpc-swagger --save\n```\n```bash\nyarn add trpc-swagger\n```\n```bash\npnpm add trpc-swagger\n```\n```bash\nbun add trpc-swagger\n```\n\n**2. Add `OpenApiMeta` to your tRPC instance**\n\n```typescript\n// @/server/trpc.ts\nimport { initTRPC } from '@trpc/server'\nimport { OpenApiMeta } from 'trpc-swagger'\n\n// VERC: This\nconst t = initTRPC.create()\n\n// VERC: Becomes\nconst t = initTRPC.meta().create()\n\n// VERC: Advanced create configs\nconst t = initTRPC.meta().create({ ... })\n```\n\n**3. Enable `openapi` support for a procedure.**\n\n\n```typescript\n// @/server/index.ts\nexport const appRouter = t.router({\n sayHello: t.procedure\n .meta({ \n openapi: { method: 'GET', path: '/say-hello' } \n })\n .input(z.object({ \n name: z.string() \n }))\n .output(z.object({ \n greeting: z.string() \n }))\n .query(({ input }) => {\n return { greeting: `Hello ${input.name}!` }\n })\n})\n```\n\n**4. Generate an OpenAPI document.**\n\n```typescript\n// @/server/swagger.ts\nimport { generateOpenApiDocument } from 'trpc-swagger'\nimport { appRouter } from './appRouter'\n\n/* 👇 */\nexport const openApiDocument = generateOpenApiDocument(appRouter, {\n title: 'tRPC Swagger',\n version: '1.0.0', // consider making this pull version from package.json\n baseUrl: 'http://localhost:3000', // consider making this dynamic\n docsUrl: \"https://github.com/vercjames/package-trpc-swagger\",\n tags: [\"tag1\", \"tag2\", \"tag3\", \"posts\"],\n})\n```\n\n**5. Add an `trpc-swagger` handler to your app.**\n\nWe currently support adapters for [`Express`](http://expressjs.com/), [`Next.js`](https://nextjs.org/), [`Next.js 14`](https://nextjs.org/), [`Serverless`](https://www.serverless.com/), [`Fastify`](https://www.fastify.io/), [`Nuxt`](https://nuxtjs.org/) & [`Node:HTTP`](https://nodejs.org/api/http.html).\n\n```typescript\nimport http from 'http'\nimport { createOpenApiHttpHandler } from 'trpc-swagger'\n\nimport { appRouter } from '../appRouter'\n\nconst server = http.createServer(createOpenApiHttpHandler({ router: appRouter })) /* 👈 */\n\nserver.listen(3000)\n```\n\n**6. Profit 🤑**\n\n```typescript\n// client.ts\nconst res = await fetch('http://localhost:3000/say-hello?name=Verc', { method: 'GET' })\nconst body = await res.json() /* { greeting: 'Hello Verc!' } */\n```\n\n## Requirements\n\n**Peer dependencies**\n\nYour application requires these 2 packages installed\n- [`tRPC`](https://github.com/trpc/trpc) Server v110 (`@trpc/server`) must be installed.\n- [`Zod`](https://github.com/colinhacks/zod) v3 (`zod@^3.14.4`) must be installed (recommended `^3.20.0`).\n\n\n**Procedure support**\n\nFor a procedure to support OpenAPI the following _must_ be true:\n\n- Both `input` and `output` parsers are present AND use `Zod` validation.\n- Query `input` parsers extend `Object<{ [string]: String | Number | BigInt | Date }>` or `Void`.\n- Mutation `input` parsers extend `Object<{ [string]: AnyType }>` or `Void`.\n- `meta.openapi.method` is `GET`, `POST`, `PATCH`, `PUT` or `DELETE`.\n- `meta.openapi.path` is a string starting with `/`.\n- `meta.openapi.path` parameters exist in `input` parser as `String | Number | BigInt | Date`\n\nPlease note:\n\n- Data [`transformers`](https://trpc.io/docs/data-transformers) (such as `superjson`) are ignored.\n- Trailing slashes are ignored.\n- Routing is case-insensitive.\n\n## HTTP Requests\n\nProcedures with a `GET`/`DELETE` method will accept inputs via URL `query parameters`. Procedures with a `POST`/`PATCH`/`PUT` method will accept inputs via the `request body` with a `application/json` or `application/x-www-form-urlencoded` content type.\n\n### Path parameters\n\nA procedure can accept a set of inputs via URL path parameters. You can add a path parameter to any OpenAPI procedure by using curly brackets around an input name as a path segment in the `meta.openapi.path` field.\n\n### Query parameters\n\nQuery & path parameter inputs are always accepted as a `string`. This library will attempt to [coerce](https://github.com/colinhacks/zod#coercion-for-primitives) your input values to the following primitive types out of the box: `number`, `boolean`, `bigint` and `date`. If you wish to support others such as `object`, `array` etc. please use [`z.preprocess()`](https://github.com/colinhacks/zod#preprocess).\n\n```typescript\n// Router\nexport const appRouter = t.router({\n sayHello: t.procedure\n .meta({ openapi: { method: 'GET', path: '/say-hello/{name}' /* 👈 */ } })\n .input(z.object({ name: z.string() /* 👈 */, greeting: z.string() }))\n .output(z.object({ greeting: z.string() }))\n .query(({ input }) => {\n return { greeting: `${input.greeting} ${input.name}!` }\n })\n})\n\n// Client\nconst res = await fetch('http://localhost:3000/say-hello/Verc?greeting=Hello' /* 👈 */, {\n method: 'GET',\n})\nconst body = await res.json() /* { greeting: 'Hello Verc!' } */\n```\n\n### Request body\n\n```typescript\n// Router\nexport const appRouter = t.router({\n sayHello: t.procedure\n .meta({ openapi: { method: 'POST', path: '/say-hello/{name}' /* 👈 */ } })\n .input(z.object({ name: z.string() /* 👈 */, greeting: z.string() }))\n .output(z.object({ greeting: z.string() }))\n .mutation(({ input }) => {\n return { greeting: `${input.greeting} ${input.name}!` }\n })\n})\n\n// Client\nconst res = await fetch('http://localhost:3000/say-hello/Verc' /* 👈 */, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ greeting: 'Hello' }),\n})\nconst body = await res.json() /* { greeting: 'Hello Verc!' } */\n```\n\n### Custom headers\n\nAny custom headers can be specified in the `meta.openapi.headers` array, these headers will not be validated on request. Please consider using [Authorization](#authorization) for first-class OpenAPI auth/security support.\n\n## HTTP Responses\n\nStatus codes will be `200` by default for any successful requests. In the case of an error, the status code will be derived from the thrown `TRPCError` or fallback to `500`.\n\nYou can modify the status code or headers for any response using the `responseMeta` function. Extra responses can be documented in the `meta.openapi.extraResponses` field.\n\n```typescript\n// Router\nexport const appRouter = t.router({\n sayHello: t.procedure\n .meta({ openapi: {\n method: 'POST',\n path: '/say-hello/{name}',\n extraResponses: {\n 400: {\n description: 'Bad request',\n content: z.object({ reason: z.string().describe(\"The reason\") }),\n },\n }\n }})\n .input(z.object({ name: z.string(), greeting: z.string() }))\n .output(z.object({ greeting: z.string() }))\n .mutation(({ input }) => {\n return { greeting: `${input.greeting} ${input.name}!` }\n })\n})\n\n```\n\nPlease see [error status codes here](packages/adapters/node-http/errors.ts).\n\n## Authorization\n\nTo create protected endpoints, add `protect: true` to the `meta.openapi` object of each tRPC procedure. By default, you can then authenticate each request with the `createContext` function using the `Authorization` header with the `Bearer` scheme. If you wish to authenticate requests using a different/additional methods (such as custom headers, or cookies) this can be overwritten by specifying `securitySchemes` object.\n\nExplore a [complete example here](examples/with-nextjs/src/server/router.ts).\n\n#### Server\n\n```typescript\nimport { TRPCError, initTRPC } from '@trpc/server'\nimport { OpenApiMeta } from 'trpc-swagger'\n\ntype User = { id: string, name: string }\n\nconst users: User[] = [\n {\n id: 'usr_123',\n name: 'Verc',\n },\n]\n\nexport type Context = { user: User | null }\n\nexport const createContext = async ({ req, res }): Promise => {\n let user: User | null = null\n if (req.headers.authorization) {\n const userId = req.headers.authorization.split(' ')[1]\n user = users.find((_user) => _user.id === userId)\n }\n return { user }\n}\n\nconst t = initTRPC.context().meta().create()\n\nexport const appRouter = t.router({\n sayHello: t.procedure\n .meta({ openapi: { method: 'GET', path: '/say-hello', protect: true /* 👈 */ } })\n .input(z.void()) // no input expected\n .output(z.object({ greeting: z.string() }))\n .query(({ input, ctx }) => {\n if (!ctx.user) {\n throw new TRPCError({ message: 'User not found', code: 'UNAUTHORIZED' })\n }\n return { greeting: `Hello ${ctx.user.name}!` }\n }),\n})\n```\n\n#### Client\n\n```typescript\nconst res = await fetch('http://localhost:3000/say-hello', {\n method: 'GET',\n headers: { Authorization: 'Bearer usr_123' } /* 👈 */,\n})\nconst body = await res.json() /* { greeting: 'Hello Verc!' } */\n```\n\n## Examples\n\n_For advanced use-cases, please find examples in our [complete test suite](tests)._\n\n#### With Express\n\nPlease see [full example here](examples/with-express).\n\n```typescript\nimport { createExpressMiddleware } from '@trpc/server/adapters/express'\nimport express from 'express'\nimport { createOpenApiExpressMiddleware } from 'trpc-swagger'\n\nimport { appRouter } from '../appRouter'\n\nconst app = express()\n\napp.use('/api/trpc', createExpressMiddleware({ router: appRouter }))\napp.use('/api', createOpenApiExpressMiddleware({ router: appRouter })) /* 👈 */\n\napp.listen(3000)\n```\n\n#### With Next.js\n\nPlease see [full example here](examples/with-nextjs).\n\n```typescript\n// pages/api/[...trpc].ts\nimport { createOpenApiNextHandler } from 'trpc-swagger'\n\nimport { appRouter } from '../../server/appRouter'\n\nexport default createOpenApiNextHandler({ router: appRouter })\n```\n\n#### With AWS Lambda\n\nPlease see [full example here](examples/with-serverless).\n\n```typescript\nimport { createOpenApiAwsLambdaHandler } from 'trpc-swagger'\n\nimport { appRouter } from './appRouter'\n\nexport const openApi = createOpenApiAwsLambdaHandler({ router: appRouter })\n```\n\n#### With Fastify\n\nPlease see [full example here](examples/with-fastify).\n\n```typescript\nimport { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify'\nimport Fastify from 'fastify'\nimport { fastifyTRPCOpenApiPlugin } from 'trpc-swagger'\n\nimport { appRouter } from './router'\n\nconst fastify = Fastify()\n\nasync function main() {\n await fastify.register(fastifyTRPCPlugin, { router: appRouter })\n await fastify.register(fastifyTRPCOpenApiPlugin, { router: appRouter }) /* 👈 */\n\n await fastify.listen({ port: 3000 })\n}\n\nmain()\n```\n\n## Types\n\n#### GenerateOpenApiDocumentOptions\n\nPlease see [full typings here](packages/generator/index.ts).\n\n| Property | Type | Description | Required |\n| ----------------- | -------------------------------------- | ------------------------------------------------------- | -------- |\n| `title` | `string` | The title of the API. | `true` |\n| `description` | `string` | A short description of the API. | `false` |\n| `version` | `string` | The version of the OpenAPI document. | `true` |\n| `baseUrl` | `string` | The base URL of the target server. | `true` |\n| `docsUrl` | `string` | A URL to any external documentation. | `false` |\n| `tags` | `string[]` | A list for ordering endpoint groups. | `false` |\n| `securitySchemes` | `Record` | Defaults to `Authorization` header with `Bearer` scheme | `false` |\n\n#### OpenApiMeta\n\nPlease see [full typings here](packages/types.ts).\n\n| Property | Type | Description | Required | Default |\n| ---------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------- |\n| `enabled` | `boolean` | Exposes this procedure to `trpc-swagger` adapters and on the OpenAPI document. | `false` | `true` |\n| `method` | `HttpMethod` | HTTP method this endpoint is exposed on. Value can be `GET`, `POST`, `PATCH`, `PUT` or `DELETE`. | `true` | `undefined` |\n| `path` | `string` | Pathname this endpoint is exposed on. Value must start with `/`, specify path parameters using `{}`. | `true` | `undefined` |\n| `protect` | `boolean` | Requires this endpoint to use a security scheme. | `false` | `false` |\n| `summary` | `string` | A short summary of the endpoint included in the OpenAPI document. | `false` | `undefined` |\n| `description` | `string` | A verbose description of the endpoint included in the OpenAPI document. | `false` | `undefined` |\n| `tags` | `string[]` | A list of tags used for logical grouping of endpoints in the OpenAPI document. | `false` | `undefined` |\n| `headers` | `ParameterObject[]` | An array of custom headers to add for this endpoint in the OpenAPI document. | `false` | `undefined` |\n| `contentTypes` | `ContentType[]` | A set of content types specified as accepted in the OpenAPI document. | `false` | `['application/json']` |\n| `extraResponses` | `ResponsesObject`* | An array of custom responses to add for this endpoint in the OpenAPI document in addition to the default response. | `false` | `undefined` |\n| `deprecated` | `boolean` | Whether or not to mark an endpoint as deprecated | `false` | `false` |\n\n* _The `content` field in ResponsesObject is expected to be a `z.ZodType`_\n\n#### CreateOpenApiNodeHttpHandlerOptions\n\nPlease see [full typings here](packages/adapters/node-http/core.ts).\n\n| Property | Type | Description | Required |\n| --------------- | ---------- | ------------------------------------------------------ | -------- |\n| `router` | `Router` | Your application tRPC router. | `true` |\n| `createContext` | `Function` | Passes contextual (`ctx`) data to procedure resolvers. | `false` |\n| `responseMeta` | `Function` | Returns any modifications to statusCode & headers. | `false` |\n| `onError` | `Function` | Called if error occurs inside handler. | `false` |\n| `maxBodySize` | `number` | Maximum request body size in bytes (default: 100kb). | `false` |\n\n---\n\n_Still using tRPC v9? See our [`.interop()`](examples/with-interop) example._\n\n## Publishing to npm\n\n> Maintainers only. The package is published from the repo root as [`trpc-swagger`](https://www.npmjs.com/package/trpc-swagger).\n\n**1. Authenticate with npm**\n\nYou must be logged in as a maintainer of the `trpc-swagger` package.\n\n```bash\nnpm whoami # confirm you're logged in — otherwise run: npm login\n```\n\n**2. Bump the version**\n\nUpdate `version` in `package.json` following [semver](https://semver.org/) (e.g. `2.0.1` → `2.0.2`).\n\n**3. Temporarily disable `private`**\n\nThe root `package.json` sets `\"private\": true` because Yarn workspaces (the `examples/*` projects) require it. npm refuses to publish private packages, so flip it just for the release:\n\n```jsonc\n// package.json\n\"private\": false\n```\n\n**4. Preview the tarball**\n\nThe `prepublishOnly` script automatically runs `rimraf build && yarn build`, so the dist is rebuilt on publish. Preview exactly what will ship first:\n\n```bash\nnpm publish --dry-run\n```\n\nOnly `build/`, `packages/`, `package.json`, `LICENSE`, and `README.md` are included — the `examples/` are excluded (see `.npmignore`).\n\n**5. Publish**\n\n```bash\nnpm publish\n```\n\n`trpc-swagger` is unscoped, so it publishes publicly by default.\n\n**6. Restore `\"private\": true`**\n\nSet it back so Yarn workspaces keep working locally, then commit the bump and tag the release:\n\n```bash\ngit commit -am \"vX.Y.Z\"\ngit tag vX.Y.Z\ngit push --follow-tags\n```\n\n## License\n\nDistributed under the MIT License. See LICENSE for more information.\n","readmeFilename":"README.md"}
![](\"https://img.shields.io/npm/v/trpc-swagger.svg?style=flat&color=brightgreen\")
\n ![](\"https://img.shields.io/badge/license-MIT-black\"){kind=icon}
\n ![](\"https://img.shields.io/badge/chat-discord-blue.svg\"){kind=icon}
\n