OpenAPI-TS for Typescript Client Generation

[chasetmartin]

Pros and Cons Discussion for Using OpenAPI-TS for TypeScript Client Generation

Introduction/Problem/Context

Building a refine.dev application with frequent API changes can be challenging when keeping the frontend in sync with the backend, having to update Interface files manually.

The goal for integrating OpenAPI-TS would be to partially automate type and client updates by running a code generation script whenever the OpenAPI spec changes on the backend, while maintaining manual control over when and how these updates are integrated.

@hey-api/openapi-ts is an OpenAPI-to-TypeScript code generation tool that can produce TypeScript type definitions and a fully-typed API client (SDK) from an OpenAPI 3.x spec. It supports OpenAPI v2, v3.0, v3.1 and offers flexible plugins for different runtimes (Fetch, Axios, Next.js, etc.) and validations (e.g., Zod schemas). Essentially, it can auto-generate files for your API’s types and endpoint calls, ensuring the frontend Refine data provider stays aligned with the backend API contract.

---

⭐️ Pros of Using OpenAPI-TS for Client Generation

Up-to-Date Type Safety and Consistency

• Ensures frontend models and request/response shapes always match the backend, or break when the SDK is updated to match the backend.
• API changes and a new SDK generation script (e.g. new required fields) immediately trigger TypeScript errors.
• Strong typing provides a fast feedback loop, reducing bugs.

Reduced Manual Effort and Boilerplate

• Reduces hand-writing endpoint functions and types/interfaces in Refine.
• Regeneration is as straightforward as a call npm run openapi-ts.
• Huge time saver for frequently changing APIs

Reliable and Well-Supported Tooling

• Open-source, MIT-licensed, with millions of monthly downloads.
  -OpenAPI-TS

Comprehensive Type Coverage

• Types for request bodies, query/path params, responses, and reusable schema components.
• No need to manually track or update field definitions.
• Consistent types means great integration with IDE 'IntelliSence'. Example from my dev env:

Ready-to-Use API Client Functions

• Auto-generated functions like addEntity(data) for API calls.
• Simplifies integration by avoiding repetitive fetch/axios code.
• Can serve as a base for refine data providers by bringing these function into the Refine data provider hooks like getOne, etc.

---

⛔️ Cons of Using OpenAPI-TS with Client Generation

Initial Setup & Learning Curve

• Requires configuring the generator and producing a valid openapi.json (this part is handled by FastAPI)
• Adds a new tool for the team to learn and integrate.
• More complex than writing plain TypeScript interfaces.

Generated Code Maintenance

• Generated files that change often and can cause large PR diffs.
• Must not be edited directly—source of truth is always the OpenAPI spec if you're doing constant changes and new client generation
• Requires discipline to manage regenerations and avoid drift.
• Can potentially drift quickly if custom function are needed.

Integration with Refine Data Layer

• Generated SDK must be wired into refine’s dataProvider manually (although that should just be one file)
• Not plug-and-play, but effort is moderate and one-time.

Naming and Style Concerns

• Function names depend on OpenAPI operationIds or path structure.
• Without good operationIds, naming may be cryptic or verbose.

Handling Complex API Features

• Some generators may fallback to any or generate overly broad types.
• For basic CRUD, this is less of a concern.

Frequent Updates and Workflow Overhead

• Developers must remember to regenerate the client after every spec change.
• Can cause merge conflicts or break unrelated features if not coordinated.
• Requires good process around spec changes and regeneration.

---

More Thoughts

Adopting automatic TypeScript client generation means the API spec is the single source of truth. It ensures type consistency, could improve developer velocity during times when the api is changing quickly, and could prevent integration bugs.

A good consistent workflow would be critical: OpenAPI spec changes > TS client generation/update > front end updates > commit and merge