https://github.com/codewithagents/openapi-ts
Glue packages for TypeScript — connecting OpenAPI, forms, validation and React Query
https://github.com/codewithagents/openapi-ts
agents library openapi typescript
Last synced: 25 days ago
JSON representation
Glue packages for TypeScript — connecting OpenAPI, forms, validation and React Query
- Host: GitHub
- URL: https://github.com/codewithagents/openapi-ts
- Owner: codewithagents
- Created: 2026-05-21T21:41:22.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-30T20:48:18.000Z (25 days ago)
- Last Synced: 2026-05-30T21:12:12.728Z (25 days ago)
- Topics: agents, library, openapi, typescript
- Language: TypeScript
- Homepage: https://glue.codewithagents.de/
- Size: 10 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# CodeWithAgents OpenAPI
[](https://github.com/codewithagents/openapi-ts/actions/workflows/ci.yml)
[](https://github.com/codewithagents/openapi-ts/actions/workflows/codeql.yml)
[](https://codecov.io/gh/codewithagents/openapi-ts)
[](./packages/openapi-gen/LICENSE)
> TypeScript bridge between your OpenAPI spec and your frontend, zero runtime footprint.
You consume a REST API. You need TypeScript types, a fetch client, form error mapping, and React Query hooks. Instead of hand-writing all of this (and keeping it in sync every time the spec changes), you run one command. Everything here is a `devDependency` or generates code that only depends on what your project already has.
---
## Packages
| Package | Version | Coverage | Description |
|---|---|---|---|
| [`@codewithagents/api-errors`](./packages/api-errors) | [](https://npmjs.com/package/@codewithagents/api-errors) | [](https://codecov.io/gh/codewithagents/openapi-ts) | Map API error responses to form field errors, framework-agnostic core + React Hook Form adapter |
| [`@codewithagents/openapi-gen`](./packages/openapi-gen) | [](https://npmjs.com/package/@codewithagents/openapi-gen) | [](https://codecov.io/gh/codewithagents/openapi-ts) | Generate TypeScript models + native `fetch` client + Zod schemas from an OpenAPI 3.x spec |
| [`@codewithagents/openapi-react-query`](./packages/openapi-react-query) | [](https://npmjs.com/package/@codewithagents/openapi-react-query) | [](https://codecov.io/gh/codewithagents/openapi-ts) | Generate typed React Query v5 hooks: `useQuery`, `useMutation`, key factories |
| [`@codewithagents/openapi-server`](./packages/openapi-server) | [](https://npmjs.com/package/@codewithagents/openapi-server) | [](https://codecov.io/gh/codewithagents/openapi-ts) | Generate a framework-agnostic service interface from OpenAPI 3.x. Optional Hono router included, or skip it and wire to any framework you choose |
Each package has its own README with full usage docs and configuration reference.
---
## Full pipeline
One spec, four generators:
```
spec/api.json
├── openapi-gen → models.ts, client.ts (TypeScript types + fetch client)
├── openapi-server → service.ts (framework-agnostic service interface)
│ router.ts (optional — Hono, or wire to any framework)
└── openapi-react-query → hooks.ts (React Query v5 hooks)
```
You write: your business logic (implement the service interface).
Everything else is generated and stays in sync when the spec changes.
---
## Philosophy
**Zero footprint.** Every package is a `devDependency` or generates code that uses only what your project already has. We never add a runtime dependency you didn't choose.
**Latest only.** TypeScript 6 (actively supported), OpenAPI 3.x (3.1.1 primary target), Zod v4, React Query v5. No legacy shims, no backports. Opinionated cuts mean less code, faster iteration, and a clear upgrade path.
**You own the output.** The Zod schema file is bootstrapped once and never overwritten. Add your own validation rules, error messages, and business logic. The generator treats your file as source of truth.
**Readable output.** Generated code looks like code you'd write yourself — no opaque abstractions, no minified magic. You can read it, review it, and commit it.
**Agent-friendly.** One `devDependency`, one command, a fully-typed API client with runtime validation. Designed to work well when an AI agent is building or maintaining your project.
---
## Why quality matters
Code generators have a wide blast radius. A subtle regression in the generator touches every project that runs it. These are the layers we use to catch problems before they reach you.
**Near-100% test coverage.** All four packages run at 100% statements, functions, and lines. Branches sit at 99%+ across the board. The remaining gap is a handful of genuinely unreachable defensive guards (`?? fallback` patterns where the fallback can never trigger by construction). Coverage is tracked per-package via [Codecov](https://codecov.io/gh/codewithagents/openapi-ts) and blocks PRs when it drops.
**128 real-world OpenAPI specs.** The generator runs against a [compatibility matrix](./examples/) of 128 publicly available specs: Stripe, GitHub, Google Calendar, Spotify, Twitter/X, OpenAI, Adyen, Slack, Vercel, Cloudflare, Twilio, Plaid, Notion, Jira, Okta, and more. **128/128 generate without errors** on every PR. The 13 showcase specs (`1Password Connect`, `Adyen Checkout`, `Adyen Legal Entity`, `Canada Holidays`, `Dev.to`, `Exchange Rate`, `Open-Meteo`, `OpenAI`, `Petstore`, `Redocly Museum`, `Resend`, `Spotify`, `Twitter`) have committed output and are drift-checked on every relevant PR. If anything regresses, CI fails.
**Smoke tests against live public APIs.** The generated client code fires real HTTP requests against public no-auth APIs (Open-Meteo, Canada Holidays, Exchange Rate API, D&D 5e) on every push to main and weekly on a schedule. This is the generated code itself making network calls, not just checking that it compiles. If the generator produces a client that breaks at runtime, the smoke suite catches it.
**Mutation testing with Stryker.** `openapi-gen` and `openapi-react-query` run [Stryker](https://stryker-mutator.io/) mutation tests locally. Mutation testing deliberately introduces bugs into the source code and verifies that the test suite catches them. High line coverage that doesn't actually catch regressions shows up here.
**Full-stack E2E tests.** The [`petstore`](./packages/petstore-hono) package is a complete runnable full-stack app: one spec drives generated types, fetch client, React Query hooks, a Hono server with Zod validation, and end-to-end [Playwright](https://playwright.dev/) tests. Every PR runs the full round-trip — spec change to browser assertion.
**Static analysis on every PR.** [Fallow](https://github.com/fallow-rs/fallow) runs on every pull request and posts inline review comments flagging dead code, duplication, and unresolved imports introduced by the diff. [CodeQL](https://github.com/codewithagents/openapi-ts/actions/workflows/codeql.yml) handles security scanning.
See [`examples/README.md`](./examples/README.md) for the full compatibility breakdown.
---
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
---
## Sponsors
This project is MIT-licensed and free to use. If it saves you time, consider sponsoring:
[](https://github.com/sponsors/codewithagents)
---
## License
[MIT](./packages/openapi-gen/LICENSE) © codewithagents