Skip to content
ShipWorthyAIPublic

About

ShipWorthy OpenAPI

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

@shipworthy/openapi

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.

Quick start

Install the CLI and the TypeScript generator in your project:

bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescript

Lint 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/generated

The 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.

Packages

Each package's README includes installation instructions, examples, and API documentation.

Code generation and clients

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.

Programmatic tooling

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.

Contributing

See CONTRIBUTING.md for local setup, checks, example generation, and the release workflow.

Acknowledgments

License

MIT. See LICENSE.

About

ShipWorthy OpenAPI

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages