{"id":15091517,"url":"https://github.com/epiphone/express-openapi-typer","last_synced_at":"2026-01-05T01:05:44.165Z","repository":{"id":47938218,"uuid":"222856268","full_name":"epiphone/express-openapi-typer","owner":"epiphone","description":"Code-generation-free conversion of OpenAPI schema into typed Express request handlers","archived":false,"fork":false,"pushed_at":"2021-08-11T17:20:05.000Z","size":929,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-27T15:10:24.424Z","etag":null,"topics":["api-schema","express","express-typescript","openapi-generator","openapi3"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epiphone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-20T05:15:33.000Z","updated_at":"2019-12-09T14:29:50.000Z","dependencies_parsed_at":"2022-08-12T14:40:47.573Z","dependency_job_id":null,"html_url":"https://github.com/epiphone/express-openapi-typer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiphone%2Fexpress-openapi-typer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiphone%2Fexpress-openapi-typer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiphone%2Fexpress-openapi-typer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiphone%2Fexpress-openapi-typer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epiphone","download_url":"https://codeload.github.com/epiphone/express-openapi-typer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244945590,"owners_count":20536296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-schema","express","express-typescript","openapi-generator","openapi3"],"created_at":"2024-09-25T10:41:32.906Z","updated_at":"2026-01-05T01:05:44.092Z","avatar_url":"https://github.com/epiphone.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# express-openapi-typer\n![](https://github.com/epiphone/express-openapi-typer/workflows/CI/badge.svg) [![npm version](https://badge.fury.io/js/express-openapi-typer.svg)](https://badge.fury.io/js/express-openapi-typer)\n\n## Caution! Alpha-level software ahead. Use at your own peril\nCode-generation-free conversion of **OpenAPI v3.1** schema into **type-checked Express request handlers**.\n\nDerive Express handler types from an OpenAPI schema to get\n- type errors when a handler doesn't match the schema, and\n- auto-completion on handler path, `req.param`, `req.query`, `req.body`, `res.send()`, `res.json()` etc.\n\nNote that the library **does not perform runtime validation** against the OpenAPI schema: add something like https://github.com/Hilzu/express-openapi-validate for that purpose.\n\n**Requires OpenAPI v3.1**. This library relies heavily on existing JSON Schema tooling whereas earlier OpenAPI versions use the [OpenAPI Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) instead of pure JSON Schema. OpenAPI `v3.1` is yet unpublished; track progress [here](https://github.com/OAI/OpenAPI-Specification/issues/2025). Read more about the OpenAPI/JSON Schema divergence at https://apisyouwonthate.com/blog/openapi-and-json-schema-divergence-part-1 and how `v3.1` solves it at https://phil.tech/2019/09/07/update-openapi-json-schema/.\n\n## Install\n\n`yarn add express-openapi-typer`\n\n## Usage\n\nFirst define your OpenAPI schema as a TypeScript type:\n\n```typescript\ninterface PetStoreSchema {\n  openapi: '3.1.0'\n  info: { ... }\n  paths: {\n    '/pets': {\n        get: { ...}\n    },\n    ...\n  }\n}\n```\n\nThen override your Express router's type from\n\n```typescript\nconst router = express.Router()\n```\n\ninto the following:\n\n```typescript\nimport { OpenAPIRouter } from 'express-openapi-typer'\n\nconst router = (express.Router() as unknown) as OpenAPIRouter\u003cPetStoreSchema\u003e\n```\n\nHandler functions in `router` now get type-checked as per `PetStoreSchema`! For example when using [the full sample PetStore schema](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml) we end up with the following:\n\n![Usage sample](./doc/usage.gif)\n\n### Access OpenAPI schema type from a runtime value\n\nIt can be useful to instantiate the OpenAPI schema as a runtime value instead of just defining a type. For example when serving the schema as documentation or handling validation we need to access the schema at runtime. In cases like these combine `typeof` and [`as const`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions) to access the schema value's type:\n\n```typescript\nconst petStoreSchema = {\n  openapi: '3.1.0',\n  info: { ... },\n  paths: {\n    '/pets': {\n        get: { ... }\n    },\n    ...\n  }\n} as const // \u003c-- important!\n\ntype PetStoreSchema = typeof petStoreSchema\n```\n\n### Allow additional paths\n\nBy default `OpenAPIRouter` doesn't allow any additional handlers not defined in the OpenAPI schema. To loosen this restriction you can expand the type as follows:\n\n```typescript\nimport * as express from 'express'\n\nconst router = express.Router() as OpenAPIRouter\u003cPetStoreSchema\u003e \u0026 express.Router\n```\n\nYou can also select a subset of `express.Router` with [`Pick`/`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktk) when allowing additional methods only for a specific HTTP method, for example.\n\n## TODO\n- All the limitations from [`json-schema-type-mapper`](https://github.com/epiphone/json-schema-type-mapper) apply here as well\n- Handle request header parameters?\n- API client type checking, using Axios?\n- Figure a way out of the unfortunate `as unknown` cast\n- Support path-based `$ref`s, not just `$id`-based ones\n  - requires some sort of manual mapping as we can't take `\"#/components/schemas/NewUser\"` apart at type-level\n\n## Related projects\n- Check out [restyped](https://github.com/rawrmaan/restyped) and [rest.ts](https://github.com/hmil/rest.ts) for different approaches to type-safe REST APIs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepiphone%2Fexpress-openapi-typer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepiphone%2Fexpress-openapi-typer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepiphone%2Fexpress-openapi-typer/lists"}