DEV Community: D.S.

Generate TanStack Query Hooks from OpenAPI: Own the Last Mile

D.S. — Mon, 11 May 2026 15:03:49 +0000

When you go API-First, your OpenAPI contract should be the single source of truth across your entire stack.

Unfortunately, most community-managed generators TanStack Query generators force you into an uncomfortable tradeoff: either live with rigid, inflexible hooks, or write everything by hand and lose the benefits of type safety.

This article shows a more flexible approach.

Use @apical-ts/craft to handle all the heavy, error-prone OpenAPI work: parsing, schema generation, response unions, parameter serialization, and type inference. Then keep a thin, custom generator in your own repository for the TanStack Query layer.

The result: fully typed, clean, and highly ergonomic hooks that you fully own and can evolve as your application needs — without upstream dependencies or duplicated contract logic.

This article is the frontend counterpart to

API-First with Hono: OpenAPI to Typed Routes Without Lock-In.

When working with TanStack Query and you want to generate hooks from an OpenAPI contract, you have a few options:

implement hooks by hand trying to match the contract types
use a community-managed open source generator for the hooks layer
or keep a small custom generator in your own repository

This article shows the last option, using @apical-ts/craft to generate the contract-sensitive pieces and a lightweight local generator to emit TanStack Query hooks, as in examples/tanstack-query-hooks/.

The Real Tradeoff Is Ownership

Both the second and third approaches are still code generation. Both start from OpenAPI. What changes is who owns the last mile of the frontend integration.

Approach	Shared input	Who owns hook ergonomics
Community-managed generator	OpenAPI spec	upstream open source project
Custom local generator	OpenAPI spec	your repository

That difference matters because TanStack Query is intentionally flexible. Query keys, invalidation, mutation side effects, pagination, SSR conventions, and wrapper APIs often end up being application-specific.

The Sweet Spot: Delegate the Hard Part, Own the Hook Layer

With @apical-ts/craft you can generate:

shared Zod schemas in generated/schemas/*
route metadata in generated/routes/*
typed operation functions in generated/client/*

That means your custom hook generator does not need to solve the hardest OpenAPI problems itself. @apical-ts/craft already handles the complex, correctness-sensitive work.

At that point, the TanStack Query layer becomes a much thinner problem: read the generated client and route metadata, then wrap them in useQuery and useMutation the way your application wants.

This is also exactly the kind of layer that can be implemented or evolved very quickly with an AI coding agent.

How It Works

1. Generate the typed client, route metadata, and schemas

npx @apical-ts/craft generate \
  --client \
  -i ./swagger.json \
  -o ./generated

In the example package, this is exposed as:

pnpm run generate:client

2. Run a local generator for the TanStack Query layer

The local generator in scripts/generate-hooks.ts reads the generated client and routes, then emits hook modules under generated/tanstack-query-hooks/*.

Run it in the example template:

pnpm run generate:hooks

or by yourself:

tsx ./scripts/generate-hooks.ts

Example Usage

const { data, error, isLoading } = useFindPetsByStatus({
  query: { status: ["available"] },
});

const addPet = useAddPetMutation();

await addPet.mutateAsync({
  body: { name: "Rex", photoUrls: [] },
});

The generated hooks stay simple and fully typed:

export function useFindPetsByStatus(
  args: Parameters<typeof ops.findPetsByStatus>[0],
) {
  type Result = Awaited<ReturnType<typeof ops.findPetsByStatus>>;

  return useQuery<Result, unknown>({
    queryKey: ["findPetsByStatus", args],
    queryFn: () => ops.findPetsByStatus(args),
  });
}

Why Owning the Hook Layer Matters

Most feature requests for community generators are not about OpenAPI parsing: they’re about customization. Custom query key factories, selective invalidation, pagination helpers, optimistic updates, SSR patterns, etc.

These are exactly the kinds of changes you can implement quickly when you own the layer instead of opening an issue upstream and hoping the customization gets accepted.

Final Take

@apical-ts/craft lets you delegate the hard OpenAPI work while keeping full control over your TanStack Query experience. It’s the best of both worlds: strong types and maximum flexibility.

Ready-to-use example:

You may want to try it yourself:

https://github.com/gunzip/apical-ts/tree/main/examples/tanstack-query-hooks

API-First with Hono: OpenAPI to Typed Routes Without Lock-in

D.S. — Sun, 10 May 2026 22:04:03 +0000

When working with Hono, both code-first and API-first approaches have valid use cases.

@hono/zod-openapi is an excellent choice for many teams that prefer a code-first workflow. However, some teams deliberately choose (or are required) to adopt an API-first strategy, where the OpenAPI specification is the Single Source of Truth.

This article shows a simple, flexible way to implement API-first with Hono using @apical-ts/craft and a lightweight custom generator.

Why Some Teams Choose API-First

While code-first is often faster for small-to-medium projects, API-first becomes valuable when you want to keep the door open to potentially switch frameworks in the future.

Generally speaking, code-first typically delivers the best developer experience as your consumers are also in the TypeScript ecosystem, but it introduces framework lock-in. API-first requires a code generation step, but gives you more flexibility and independence in the long term.

The Sweet Spot: Generate the Hard Part, Keep the Framework Layer Thin

You don't have to sacrifice DX for flexibility.

With @apical-ts/craft you can generate Zod v4 schemas and "agnostic" rich route metadata directly from your openapi.yaml, then use a small custom generator to create Hono routes exactly as you want them.

How It Works

1. Generate Zod schemas and route metadata

npx @apical-ts/craft generate \
  -i ./openapi.yaml \
  -o ./src/generated \
  --routes

2. Transform the metadata with your own generator into clean, idiomatic Hono code.

You can bootstrap this generator quickly by describing the desired architecture to an AI coding agent or refer to the existing template in the @apical-ts documentation.

Here’s an example of a prompt you can use:

Goal: build type safe Hono handlers by first generating route metadata with @apical-ts/craft and then writing a generator that emits the Hono integration.

Process:
1. Run `npx @apical-ts/craft generate --routes -i openapi.yaml -o generated`.
2. Inspect `generated/routes/*` and use them as the only source of truth for `operationId`, `path`, `method`, `params`, `requestMap`, and `responseMap`.
3. Implement the generator entrypoint in `scripts/generate-hono-server.ts`.
4. Implement the generator modules under `scripts/hono-generator/*` so they read generated route metadata and emit `generated/hono/*`.
5. The generator should produce:
   - one generated Hono operation module per route
   - one handler file per operation for userland code
   - a register-routes module that mounts routes without a central handlers object
   - shared runtime helpers
6. Add a runnable Hono server that imports the generated registration layer.

Rules:
- do not hand-write `generated/hono/*`
- do not redefine endpoints or payload types outside @apical-ts/craft output
- request validation must be driven by generated schemas and metadata
- use `@hono/zod-validator` where request validation is needed

From there, use the local generator to emit the Hono-specific layer, i.e.:

tsx scripts/generate-hono-server.ts \
  --routes generated/routes \
  --output generated/hono \
  --handlers handlers

This generator can stay very opinionated about your project structure without becoming the source of truth for the contract.

Typical project layout:

src/
├── handlers/                 # ← Your business logic (not overwritten)
│   ├── pets/
│   │   ├── addPet.ts
│   │   └── getPetById.ts
├── generated/
│   └── hono/
│       ├── operations/
│       └── register-routes.ts
├── openapi.yaml
└── generators/
    └── hono-generator.ts     # ← Your custom generator

Why not let the AI generate the Zod schemas too?

Generating high-fidelity Zod schemas from OpenAPI is a surprisingly complex task. It requires deep knowledge of OpenAPI edge cases (discriminators, advanced oneOf/anyOf, nullable + required combinations, complex additionalProperties, XML support, encoding options, etc.). Even modern coding agents struggle to handle all these cases reliably and consistently, moreover, OpenAPI specs which aren't well formed needs tolerant parsers.

That's why it's smarter to use a specialized, battle-tested tool that lets you save tokens for the schema generation part, and then let the AI (or yourself) build the lighter, easier to implement (on a rock solid base), fully customizable, deterministic framework-specific generator.

The pragmatic split is:

use @apical-ts for schemas and route metadata
use AI or local code for the adapter layer
keep business logic handwritten

That gives you flexibility where it is cheap, and determinism where it is hard.

Example Handler (strongly typed):

import type { AddPetHandler } from "../../generated/hono/operations/addPet.js";

export const addPetHandler: AddPetHandler = async (input) => {
  const pet = await petService.create(input.body);

  return {
    status: "200",
    contentType: "application/json",
    data: pet,
  };
};

The generated handler type ensure that your business logic remains perfectly aligned with your contract. The handler receives an input object containing already validated body, query, headers, and path parameters.

In addition, the return type is strictly enforced at compile-time: you must return a valid combination of status, contentType, and data as defined in your OpenAPI specification.

When I would not use this

I would probably stick to code-first when:

the team is fully TypeScript-native and Hono-centric
maintaining a local generator would be overhead rather than leverage

In that case, @hono/zod-openapi is hard to beat for simplicity and speed.

`@apical-ts/craft` vs `@hono/zod-openapi`

These tools solve related but different problems.

@hono/zod-openapi is a great fit when you want:

the best immediate Hono DX
route definitions authored directly in code

@apical-ts/craft plus a local Hono generator is a better fit when you want:

OpenAPI to remain the source of truth
portable route metadata and schemas
a thinner dependency on any single server framework
the freedom to shape the generated Hono layer yourself

Final take

If you are all-in on Hono and optimizing for raw speed of iteration, code-first is still hard to beat.

But if OpenAPI needs to stay the source of truth, you do not have to accept weak DX or a rigid framework abstraction.

Generate the hard, correctness-sensitive pieces with @apical-ts/craft, keep the Hono layer thin and local, and let handlers stay close to the business domain.

That is a good middle ground between strict contract ownership and framework-level flexibility.

Ready-to-use Example

Full, ready-to-fork example showing this workflow in action:
https://github.com/gunzip/apical-ts/tree/main/examples/hono

How OpenAPI Undermines a Good Developer Experience

D.S. — Fri, 03 Oct 2025 09:36:41 +0000

In the JavaScript/TypeScript ecosystem, tools like tRPC and oRPC are gaining traction. This isn’t by chance, it signals a growing need in the JS world: moving beyond the Developer Experience imposed by OpenAPI’s schema-first approach. But why?

All OpenAPI Code Generators Are Broken

With the help of Gen-AI, I'm building a tool to generate TypeScript code from OpenAPI specs. Fighting against the standard, I uncovered a systemic issue:

All existing code generators are unreliable, and it couldn’t be otherwise.

OpenAPI specs are unnecessarily complex, creating a chaotic mess for anyone trying to automate code generation. Here’s why.

Error Handling Chaos

Error handling in OpenAPI requires a sisyphean effort. You must manually map different layers: network errors (failed fetch), server errors (5xx), client errors (4xx), and payload serialization/deserialization issues.

Each status code - (ie. 404 returning nothing, 429 providing retry parameters, 400 delivering unpredictable serialization errors, ...) may (or not) come with a payload in wildly different formats with disconnected meanings.

Therefore, a client generator cannot merely "implement retries": users must handle all this logic themselves by interpreting the returned data.

Serialization Nightmare

Take parameter serialization (ie. style and explode). You can send textual data to an endpoint in seven different ways with the same outcome. This redundancy is there for legacy reasons, pointless and breeds ambiguity everywhere.

JSON Schema Quirks

JSON Schema is a minefield of edge cases. For example, you can have an allOf intersection with and empty object that specifies a list of required fields without any schema attached.

SomeSchema:
  allOf:
    - $ref: "#/components/schemas/SomeOtherSchema"        
    - $ref: "#/components/schemas/SomeOtherSchemaAgain"
    - type: object
      required: [foo]

The generator implementation must traverse all fields of all objects in the intersection, only to mark as required - if any - those referenced by this empty object. Guess what? No know tool handles this.

Wildcard Complexity

Generators must handle vague cases like range status codes (e.g., 4XX, 5XX, ...) alongside the "default" case, adding yet another layer of complexity that’s nearly impossible to manage keeping a good DX.

A Challenge

With so many intersections and details, no tool can handle every scenario. TypeScript developers today are working with tools that are merely "good enough," if that’s even sufficient.

What’s the point of a spec if its core purpose - automatic code generation - is inherently flawed?

All existing TypeScript generators are approximate at best. You can verify this yourself against a valid OpenAPI spec.

Try find a generator that correctly handles:

Different schemas for multiple 2xx responses
Different schemas per content type
Default responses
Range status codes
Intersections with empty objects
Self references

Time to Rethink the Paradigm

Recently, I came across the Cap'n Web protocol from Cloudflare, and it clearly demonstrates a unified approach that delivers a DX unthinkable with OpenAPI.

OpenAPI solves problems that shouldn’t exist in the first place. The schema-first approach is doomed to deliver a subpar DX. It's so poor that Microsoft decided to implement its own alternative DSL just to produce OpenAPI specs. Entire commercial companies have their core product built around being a decent OpenAPI code generator (!).

For a new project - especially internal services - I would rather lean towards DX-friendly alternatives like modern RPC protocols or a code-first approach where the API specification is generated directly from the source code.

Are you using OpenAPI for internal APIs, or have you switched to something more streamlined?

OpenAPI to TypeScript: a More Reliable and Type-Safe Approach

D.S. — Sun, 14 Sep 2025 22:42:32 +0000

If you’re building REST API clients (or servers) with TypeScript, you expect type safety to save the day. But most existing OpenAPI-to-Typescript generators give a false sense of security, hiding pitfalls that can bite in production. After benchmarking 20+ tools, here’s what I found, and how I choose to fix it.

Poor error handling

Calling

const ret = await api.post({ ... })

should be safe, but the method signature often ignores network issues like DNS failures or timeouts. You’re forced to wrap it in a try/catch, but without clear documentation on what errors to expect, you’re left guessing. Even when documented, this approach is fragile and prevents efficient error handling as validation errors (versus OpenAPI specs) end up in the same bag as network errors.

Limited handling of HTTP statuses

Most generators emit types only for 2xx responses, ignoring 4xx/5xx errors with specific payloads. If the API returns a 400 or 500 with some ProblemJson, generated TypeScript types (and/or runtime schemas) won’t reflect it, leaving you vulnerable to runtime surprises.

Multiple success responses, different payloads

Some APIs return different payloads for 200 vs. 201 status codes. Many generated clients only handle the first successful status code. Other clients either treat non-200 responses as unknown errors, or merge them into some vague Typescript union, forcing further runtime checks to discriminate. What’s the point of using the generated code then?

Mishandled default responses

The smartest generators create discriminated unions for all response types (200, 201, 400, 500, etc.), but default responses (covering unspecified cases in OpenAPI) are treated as generic errors and/or lack payload typing and validation, leading to inaccurate types.

Content-type being ignored

APIs returning multiple content types require discrimination by both status code and content-type. Afaik, no existing Typescript generator supports this. Ideally, you should be able to write:

if (r.status === 200) {
 if (r.contentType === "application/json") {
    // Typescript should know that r.data is SomeJsonModel
  } else if ( r.contentType === "application/xml") {
    // Typescript should know that r.data is SomeXmlModel
  }
}

OpenAPI Schema mismatch

OpenAPI schemas are more expressive than TypeScript types. For example, a schema defining an email string or regex pattern often becomes a plain string in TypeScript. Even tools with runtime validation struggle to support advanced OpenAPI features like string patterns or oneOf vs anyOf, leading to inaccurate types and runtime bugs.

Conclusion

After evaluating the landscape, I faced a dilemma: convince maintainers of top tools to adopt breaking changes for their thousands of users or build a new solution from scratch. I chose the latter and built an open-source TypeScript client generator that prioritizes safe, accurate types and excellent Developer Experience:

https://gunzip.github.io/apical-ts/

What's your biggest pain point with generated OpenAPI clients / servers?

I’d love to hear your thoughts to shape this project, drop a comment, or check out the prototype!

DEV Community: D.S.

Generate TanStack Query Hooks from OpenAPI: Own the Last Mile

The Real Tradeoff Is Ownership

The Sweet Spot: Delegate the Hard Part, Own the Hook Layer

How It Works

Example Usage

Why Owning the Hook Layer Matters

Final Take

API-First with Hono: OpenAPI to Typed Routes Without Lock-in

Why Some Teams Choose API-First

The Sweet Spot: Generate the Hard Part, Keep the Framework Layer Thin

How It Works

Why not let the AI generate the Zod schemas too?

When I would not use this

@apical-ts/craft vs @hono/zod-openapi

Final take

Ready-to-use Example

How OpenAPI Undermines a Good Developer Experience

All OpenAPI Code Generators Are Broken

Error Handling Chaos

Serialization Nightmare

JSON Schema Quirks

Wildcard Complexity

A Challenge

Time to Rethink the Paradigm

OpenAPI to TypeScript: a More Reliable and Type-Safe Approach

Poor error handling

Limited handling of HTTP statuses

Multiple success responses, different payloads

Mishandled default responses

Content-type being ignored

OpenAPI Schema mismatch

Conclusion

`@apical-ts/craft` vs `@hono/zod-openapi`