\n\n`openapi-ts-router` turns generated OpenAPI `paths` into typed Express and Hono route methods. You keep native routers, handlers, and middleware, while OpenAPI controls which paths compile, which request schemas are required, and what JSON success bodies handlers can return.\n\n- Keep OpenAPI path syntax in route code while the wrapper registers framework routes\n- Catch wrong paths, wrong methods, missing required schemas, and wrong JSON success responses in TypeScript\n- Validate path params, query params, and JSON bodies with any [Standard Schema](https://standardschema.dev/) library\n- Read parsed and validated values from `req.valid` in Express or `c.req.valid()` in Hono\n- Add OpenAPI-backed routes without replacing your existing Express or Hono app\n\nExpress:\n\n```ts\nimport { Router } from 'express';\nimport { createExpressOpenApiRouter } from 'openapi-ts-router/express';\nimport * as z from 'zod';\nimport type { paths } from './gen/openapi';\n\nconst router = Router();\nconst openApiRouter = createExpressOpenApiRouter(router);\n\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: z.object({\n petId: z.number()\n }),\n handler: (req, res) => {\n const { petId } = req.valid.path;\n res.json({ name: `Pet ${petId}`, photoUrls: [] });\n }\n});\n```\n\nHono:\n\n```ts\nimport { Hono } from 'hono';\nimport { createHonoOpenApiRouter } from 'openapi-ts-router/hono';\nimport * as v from 'valibot';\nimport type { paths } from './gen/openapi';\n\nconst app = new Hono();\nconst openApiRouter = createHonoOpenApiRouter(app);\n\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: v.object({\n petId: v.number()\n }),\n handler: (c) => {\n const { petId } = c.req.valid('param');\n return c.json({ name: `Pet ${petId}`, photoUrls: [] });\n }\n});\n```\n\nMigrating from `0.3.x`? See [MIGRATION.md](./MIGRATION.md).\n\n## Install\n\nInstall the router package and the OpenAPI type generator:\n\n```sh\nnpm install openapi-ts-router\nnpm install -D openapi-typescript\n```\n\nInstall the framework and validator you use:\n\n```sh\n# Express\nnpm install express\nnpm install -D @types/express\n\n# Hono\nnpm install hono\n\n# Standard Schema validator\nnpm install zod\n# or\nnpm install valibot\n```\n\nGenerate TypeScript types from your OpenAPI document:\n\n```sh\nnpx openapi-typescript ./openapi.yaml -o ./src/gen/openapi.ts\n```\n\nThe generated file must export the `paths` type from `openapi-typescript`.\n\n## Usage\n\nCreate a router wrapper with your generated `paths` type. The wrapper keeps your framework router, but narrows each route method to paths that exist in your OpenAPI schema.\n\nPass OpenAPI path strings such as `/pet/{petId}` to `openApiRouter`. The wrapper registers the framework route as `/pet/:petId` for Express and Hono. Do not use framework `:param` syntax in `openApiRouter` calls.\n\n### Express\n\n```ts\nimport express, { Router } from 'express';\nimport { createExpressOpenApiRouter } from 'openapi-ts-router/express';\nimport * as z from 'zod';\nimport type { paths } from './gen/openapi';\n\nconst app = express();\nconst router = Router();\nconst openApiRouter = createExpressOpenApiRouter(router);\n\napp.use(express.json());\napp.use(router);\n\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: z.object({\n petId: z.number()\n }),\n handler: (req, res) => {\n const { petId } = req.valid.path;\n res.json({ name: `Pet ${petId}`, photoUrls: [] });\n }\n});\n\nopenApiRouter.post('/pet', {\n bodySchema: z.object({\n name: z.string(),\n photoUrls: z.array(z.string())\n }),\n handler: (req, res) => {\n const { name, photoUrls } = req.valid.body;\n res.json({ name, photoUrls });\n }\n});\n```\n\nExpress body validation reads `req.body`, so mount `express.json()` or an equivalent body parser before the router.\n\n### Hono\n\n```ts\nimport { Hono } from 'hono';\nimport { createHonoOpenApiRouter } from 'openapi-ts-router/hono';\nimport * as v from 'valibot';\nimport type { paths } from './gen/openapi';\n\nconst app = new Hono();\nconst openApiRouter = createHonoOpenApiRouter(app);\n\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: v.object({\n petId: v.number()\n }),\n handler: (c) => {\n const { petId } = c.req.valid('param');\n return c.json({ name: `Pet ${petId}`, photoUrls: [] });\n }\n});\n\nopenApiRouter.post('/pet', {\n bodySchema: v.object({\n name: v.string(),\n photoUrls: v.array(v.string())\n }),\n handler: (c) => {\n const { name, photoUrls } = c.req.valid('json');\n return c.json({ name, photoUrls });\n }\n});\n```\n\n## What TypeScript Checks\n\n`openapi-ts-router` ties route registration to one OpenAPI operation.\n\n```ts\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: z.object({ petId: z.number() }),\n handler: (req, res) => {\n req.valid.path.petId; // number\n res.json({ name: 'Falko', photoUrls: [] }); // checked against the 2xx JSON response\n }\n});\n```\n\nThese mistakes fail before runtime:\n\n```ts\n// The OpenAPI path has no POST operation.\nopenApiRouter.post('/store/inventory', {\n handler: () => undefined\n});\n\n// The OpenAPI path has required path params, so pathSchema is required.\nopenApiRouter.get('/pet/{petId}', {\n handler: (_req, res) => {\n res.json({ name: 'Falko', photoUrls: [] });\n }\n});\n\n// The success response must match the OpenAPI 2xx JSON response body.\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: z.object({ petId: z.number() }),\n handler: (_req, res) => {\n res.json('not a pet');\n }\n});\n```\n\n## Route Config\n\n| Option | Description |\n| ------------------ | -------------------------------------------------------------------------------------------------------------------- |\n| `handler` | Native Express or Hono handler called after parsing, validation, and route middleware |\n| `middleware` | Native Express or Hono middleware for this route. Runs after validation and before `handler` |\n| `pathSchema` | Standard Schema validator for OpenAPI path params. Required when the OpenAPI operation has required path params |\n| `querySchema` | Standard Schema validator for OpenAPI query params. Required when the OpenAPI operation has required query params |\n| `bodySchema` | Standard Schema validator for the JSON request body. Required when the OpenAPI operation has a required request body |\n| `pathParamParser` | Route-level path param parser override. Set to `false` to validate raw router strings |\n| `queryParamParser` | Route-level query param parser override. Set to `false` to validate raw router query values |\n\nRequired OpenAPI request parts require matching schemas at compile time. Optional request parts may omit their schemas.\n\n## Validated Data\n\nParsed values, and validated values when a schema runs, are stored separately from the raw framework request data:\n\n| Request part | Express | Hono |\n| ------------ | ----------------- | ---------------------- |\n| Path params | `req.valid.path` | `c.req.valid('param')` |\n| Query params | `req.valid.query` | `c.req.valid('query')` |\n| JSON body | `req.valid.body` | `c.req.valid('json')` |\n\nThis keeps handlers honest: `req.params`, `req.query`, and `req.body` may still contain raw framework values, while the `valid` slots contain parser output and schema output for the request parts you validated.\n\n## Param Parsing\n\nPath and query params start as strings in web frameworks. By default, `openapi-ts-router` runs `parseParams()` before validation:\n\n- `'123'` becomes `123`\n- `'true'` and `'false'` become booleans\n- `'null'` becomes `null`\n- repeated query params stay arrays\n- nested query objects and arrays are parsed recursively\n\nSet parser defaults on the router:\n\n```ts\nconst openApiRouter = createExpressOpenApiRouter(router, {\n pathParamParser: false,\n queryParamParser: false\n});\n```\n\nOverride parsing for one route when a value should stay raw:\n\n```ts\nimport { parseParams } from 'openapi-ts-router';\n\nopenApiRouter.get('/items/{sku}', {\n pathParamParser: (params) => ({\n ...parseParams(params),\n sku: params['sku']\n }),\n pathSchema: z.object({\n sku: z.string()\n }),\n handler: (req, res) => {\n res.json({ sku: req.valid.path.sku });\n }\n});\n```\n\n## Middleware\n\nUse native middleware exactly where your framework expects it. Route-level middleware receives the same typed validated data as the final handler.\n\n```ts\nopenApiRouter.get('/pet/{petId}', {\n pathSchema: z.object({ petId: z.number() }),\n middleware: [\n (req, _res, next) => {\n auditPetRead(req.valid.path.petId);\n next();\n }\n ],\n handler: (req, res) => {\n res.json({ name: `Pet ${req.valid.path.petId}`, photoUrls: [] });\n }\n});\n```\n\nGlobal Express middleware and Hono middleware still work normally around the wrapped router.\n\n## Errors\n\nValidation failures throw `OpenApiValidationError` with `status: 400` and an `issues` array.\nThe Express and Hono entrypoints re-export the shared error classes, so `instanceof` works whether errors are imported from the root package or the matching framework entrypoint.\n\n```ts\nimport type { ErrorRequestHandler } from 'express';\nimport { OpenApiValidationError } from 'openapi-ts-router/express';\n\nexport const errorMiddleware: ErrorRequestHandler = (error, _req, res, _next) => {\n if (error instanceof OpenApiValidationError) {\n res.status(error.status).json({ issues: error.issues });\n return;\n }\n\n res.status(500).json({ message: 'Internal server error' });\n};\n```\n\nHono can handle the same error through `app.onError()`:\n\n```ts\nimport { OpenApiValidationError } from 'openapi-ts-router/hono';\n\napp.onError((error, c) => {\n if (error instanceof OpenApiValidationError) {\n return c.json({ issues: error.issues }, error.status);\n }\n\n return c.json({ message: 'Internal server error' }, 500);\n});\n```\n\nRequest body parse failures and unexpected validator failures throw `OpenApiRouterError`. Request-level errors can include `status`, while internal schema failures expose `code`, `message`, and `cause`.\n\n## Examples\n\n- [Express Petstore](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore)\n- [Hono Petstore](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore)\n\n## FAQ\n\n### Why do I still write schemas when OpenAPI already has types?\n\nOpenAPI types only exist at compile time. A schema validates real requests at runtime. `openapi-ts-router` connects the two: if the OpenAPI operation requires a path param, query param, or body, TypeScript requires a matching schema before the route can compile.\n\n### Which validators can I use?\n\nAny validator that implements [Standard Schema](https://standardschema.dev/) works. Valibot and Zod are the common choices. No package-specific validation adapter is required.\n\n### Does this generate OpenAPI specs?\n\nNo. Your OpenAPI document stays the source of truth. Generate TypeScript with `openapi-typescript`, then pass the generated `paths` type to the router wrapper.\n\n### Does this validate responses at runtime?\n\nNo. JSON success responses are checked by TypeScript in handlers, but the package does not run response validators at runtime. Keep response runtime checks in tests or framework middleware if your app needs them.\n\n### What happens when I omit an optional schema?\n\nTypeScript still infers the OpenAPI request shape, but runtime validation does not run for that request part. Use a schema when handlers need trusted parsed and validated values.\n\n### Why are error responses not typed on handlers?\n\nError responses usually come from shared error handling, not the happy-path route handler. Throw domain errors or `OpenApiRouterError` values from routes, then map them to your API error shape in Express error middleware or Hono `app.onError()`.\n\n### What request parts are supported?\n\nThe router validates path params, query params, and JSON request bodies. Keep auth, headers, cookies, multipart uploads, and framework-specific request concerns in native Express or Hono middleware.\n\n### Which HTTP methods are supported?\n\n`get`, `post`, `put`, `patch`, and `delete` are supported.\n\n### Which framework versions are supported?\n\nThe package targets Express 5 and Hono 4 through peer dependencies.\n\n### Can I migrate one route at a time?\n\nYes. Wrap an existing Express router or Hono app, then register OpenAPI-backed routes through `openApiRouter`. Existing framework routes and middleware can keep running next to it while you migrate.\n","readmeFilename":""}
![\"openapi-ts-router](\"https://raw.githubusercontent.com/builder-group/community/develop/packages/openapi-ts-router/.github/banner.svg\")
\n![\"GitHub](\"https://img.shields.io/github/license/builder-group/community.svg?label=license&style=flat&colorA=293140&colorB=FDE200\")
\n \n \n ![\"NPM](\"https://img.shields.io/bundlephobia/minzip/openapi-ts-router.svg?label=minzipped%20size&style=flat&colorA=293140&colorB=FDE200\")
\n \n \n ![\"NPM](\"https://img.shields.io/npm/dt/openapi-ts-router.svg?label=downloads&style=flat&colorA=293140&colorB=FDE200\")
\n \n \n ![\"Join](\"https://img.shields.io/discord/795291052897992724.svg?label=&logo=discord&logoColor=000000&color=293140&labelColor=FDE200\")
\n \n