OpenAPI tooling for TypeScript: bundle, overlay, and lint API documents, generate types and runtime validators, and build typed Fetch and TanStack Query clients.
Accepts OpenAPI 3.0 and 3.1 documents in JSON or YAML, including external $refs. The generation
pipeline bundles references and upgrades OpenAPI 3.0 documents to 3.1 before generating code.
Install the CLI and the TypeScript generator in your project:
bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescriptLint your API document and generate TypeScript types:
bunx --bun @shipworthy/openapi-cli lint ./openapi.yaml
bunx --bun @shipworthy/openapi-cli generate typescript -i ./openapi.yaml -o ./src/generatedThe generated src/generated/types.ts exports paths, components, and operations types. Use them directly in
your application, or with @shipworthy/openapi-fetch for
typed HTTP requests.
The CLI requires Node.js 22.19.0 or later, or Bun. Packages ship ESM JavaScript and TypeScript declarations. Install only the generators you need; see the CLI documentation for bundling, other generators, and their dependencies.
Each package's README includes installation instructions, examples, and API documentation.
| Package | Use it to |
|---|---|
@shipworthy/openapi-cli |
Bundle, overlay, lint, and generate code from the command line. |
@shipworthy/openapi-typescript |
Generate TypeScript types for paths, operations, and components. |
@shipworthy/openapi-standard-schema |
Generate Standard Schema validators backed by Effect Schema. |
@shipworthy/openapi-zod |
Generate Zod 4 runtime validators. |
@shipworthy/openapi-tanstack-query |
Generate operation-based query options, keys, and mutations for TanStack Query. |
@shipworthy/openapi-react-query |
Use path-based React hooks with an API client provider. |
@shipworthy/openapi-fetch |
Make typed HTTP requests using generated paths types. |
The parsing and generation APIs use Effect 4. The pipeline parses an OpenAPI document, transforms
it into a shared ParsedService model, then passes that model to a generator plugin.
| Package | Use it to |
|---|---|
@shipworthy/openapi-overlay |
Apply OpenAPI Overlay 1.0 and 1.1 documents with Effect. |
@shipworthy/openapi-parser |
Load, bundle, upgrade, and validate OpenAPI documents. |
@shipworthy/openapi-transformer |
Convert a bundled OpenAPI document into the ParsedService HTTP model. |
@shipworthy/openapi-generator |
Run generator plugins from code or write your own. |
@shipworthy/openapi-validator |
Lint API documents with Spectral. |
See CONTRIBUTING.md for local setup, checks, example generation, and the release workflow.
@shipworthy/openapi-transformerwas inspired by @stoplightio/http-spec.@shipworthy/openapi-tanstack-querywas inspired by @orpc/tanstack-query.@shipworthy/openapi-typescriptwas inspired by openapi-typescript.@shipworthy/openapi-fetchwas inspired by openapi-fetch.
MIT. See LICENSE.