/api-framework-hono

name: api-framework-hono
description: Hono routes, OpenAPI, Zod validation

API Development with Hono + OpenAPI

> **Quick Guide:** Use Hono with `@hono/zod-openapi` for type-safe REST APIs that auto-generate OpenAPI specs. Import `z` from `@hono/zod-openapi` (NOT from `zod`) so `.openapi()` is available on all schemas. Always include `operationId` in routes and export the `app` instance for spec generation.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST import `z` from `@hono/zod-openapi`, NOT from `zod` -- this gives Zod the `.openapi()` method)**

**(You MUST export the `app` instance for OpenAPI spec generation)**

**(You MUST include `operationId` in every route for clean client generation)**

</critical_requirements>

---

**Auto-detection:** Hono, @hono/zod-openapi, OpenAPIHono, createRoute, Zod schemas with .openapi(), app.route(), createMiddleware, rate limiting, CORS configuration, health checks, hc client, RPC mode, getContext, tryGetContext, contextStorage, some/every/except middleware

**When to use:**

• Building type-safe REST APIs with auto-generated OpenAPI specs
• Defining OpenAPI specifications with automatic Zod validation
• Creating standardized error responses with proper status codes
• Implementing filtering, pagination, and sorting patterns
• Public or multi-client APIs needing formal documentation
• Production APIs requiring rate limiting, CORS, health checks

**When NOT to use:**

• Simple CRUD with no external consumers (framework-native endpoints are simpler)
• Internal-only APIs without documentation requirements
• Single-use endpoints with no schema reuse (over-engineering)

**Key patterns covered:**

• Modular route setup with `app.route()` and `OpenAPIHono`
• Zod schema definitions with `.openapi()` metadata
• Route definition with `createRoute` (operationId, tags, responses)
• Error handling with named error codes
• Filtering, pagination, and data transformation
• Auth, rate limiting, CORS, logging, caching middleware
• Health check endpoints (shallow and deep)
• RPC client (`hc`) with end-to-end type safety
• Context Storage for out-of-handler context access
• Combine Middleware (`some`/`every`/`except`) for declarative auth

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Route setup, list/detail endpoints
• [examples/validation.md](examples/validation.md) - Zod schema definitions with OpenAPI
• [examples/routes.md](examples/routes.md) - Filtering, pagination, data transformation
• [examples/middleware.md](examples/middleware.md) - Auth, rate limiting, CORS, logging, caching
• [examples/error-handling.md](examples/error-handling.md) - Standardized error responses
• [examples/openapi.md](examples/openapi.md) - Spec generation (build-time and endpoint)
• [examples/health-checks.md](examples/health-checks.md) - Liveness and readiness checks
• [examples/advanced-v4.md](examples/advanced-v4.md) - RPC, Context Storage, Combine Middleware
• [reference.md](reference.md) - Decision frameworks, anti-patterns, production checklist

---

<philosophy>

Philosophy

**Type safety + documentation from code.** Zod schemas serve both validation AND OpenAPI spec generation. Single source of truth flows to clients via generated SDKs or Hono's RPC client.

**Use Hono + OpenAPI when:** Building public/multi-client APIs, need auto-generated documentation, require formal OpenAPI specs, want type-safe validation.

**Use simpler approaches when:** Internal-only CRUD, no external API consumers, no documentation needs.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Modular Route Setup

Structure routes using `app.route()` for modularization. Export the `app` instance for spec generation.

import { OpenAPIHono } from "@hono/zod-openapi";

const app = new OpenAPIHono().basePath("/api");

app.route("/", jobsRoutes);
app.route("/", companiesRoutes);

// REQUIRED: Export app for spec generation
export { app };

**Why good:** `app.route()` prevents God files, app export enables build-time spec generation

See [examples/core.md](examples/core.md) for complete setup with framework adapter exports.

---

Pattern 2: Zod Schemas with OpenAPI Metadata

Import `z` from `@hono/zod-openapi` (not `zod`). Use `.openapi()` for schema registration and documentation.

import { z } from "@hono/zod-openapi";

const MIN_SALARY = 0;
const CURRENCY_CODE_LENGTH = 3;

export const SalarySchema = z
  .object({
    min: z.number().min(MIN_SALARY),
    max: z.number().min(MIN_SALARY),
    currency: z.string().length(CURRENCY_CODE_LENGTH),
  })
  .openapi("Salary", {
    example: { min: 60000, max: 90000, currency: "EUR" },
  });

**Why good:** importing `z` from `@hono/zod-openapi` provides `.openapi()` automatically, named constants prevent magic number bugs, `.openapi("Name")` registers as `#/components/schemas/Name`

See [examples/validation.md](examples/validation.md) for complete schema patterns.

---

Pattern 3: Route Definition with createRoute

Define routes with `createRoute` and implement with `app.openapi()`. Always include `operationId`.

import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";

const getJobsRoute = createRoute({
  method: "get",
  path: "/jobs",
  operationId: "getJobs", // Becomes client method name
  tags: ["Jobs"],
  request: { query: JobsQuerySchema },
  responses: {
    200: {
      description: "List of jobs",
      content: { "application/json": { schema: JobsResponseSchema } },
    },
  },
});

app.openapi(getJobsRoute, async (c) => {
  const { country } = c.req.valid("query"); // Type-safe validated params
  // ... handler logic
  return c.json({ jobs: results }, 200);
});

**Why good:** `operationId` becomes clean client method name (`getJobs` vs `get_api_jobs`), `c.req.valid()` enfor