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: High-Quality Schemas + Full Control

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

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), customizable, deterministic framework-specific generator.

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.

Main Advantages of This Approach

• OpenAPI stays as the source of truth
• High-quality Zod schemas (Zod v4)
• Full control over your Hono architecture, middleware, error handling, and folder structure
• Minimal lock-in: you own the translation layer
• Easy to add refinements, transformations, and custom logic on top of generated schemas
• Strong type safety

Ready-to-use Example

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