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

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