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 - Route setup, list/detail endpoints
• examples/validation.md - Zod schema definitions with OpenAPI
• examples/routes.md - Filtering, pagination, data transformation
• examples/middleware.md - Auth, rate limiting, CORS, logging, caching
• examples/error-handling.md - Standardized error responses
• examples/openapi.md - Spec generation (build-time and endpoint)
• examples/health-checks.md - Liveness and readiness checks
• examples/advanced-v4.md - RPC, Context Storage, Combine Middleware
• 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 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 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() enforces schema validation with types

See examples/core.md for list/detail endpoint examples.

---

Pattern 4: Error Handling with Named Codes

Use named error code constants for consistent, machine-parseable error responses.

export const ErrorCodes = {
  VALIDATION_ERROR: "validation_error",
  NOT_FOUND: "not_found",
  UNAUTHORIZED: "unauthorized",
  INTERNAL_ERROR: "internal_error",
} as const;

Why good: Named codes enable frontend switch handling, consistent shape across all endpoints

See examples/error-handling.md for the full handleRouteError utility.

---

Pattern 5: JWT Authentication with Explicit Algorithm

Always specify the alg option on JWT/JWK middleware to prevent algorithm confusion attacks (CVE-2026-22817, CVE-2026-22818, patched in v4.11.4+).

import { verify } from "hono/jwt";

const JWT_ALGORITHM = "HS256";

const payload = await verify(token, secret, JWT_ALGORITHM);

Why good: explicit algorithm prevents attackers from switching to symmetric verification with known public keys

See examples/middleware.md for complete auth middleware with type-safe variables.

</patterns>

---

<red_flags>

RED FLAGS

High Priority:

• Importing z from "zod" instead of "@hono/zod-openapi" -- .openapi() won't be available
• Missing operationId in routes -- generated client has ugly method names
• Not exporting app instance -- can't generate OpenAPI spec at build time
• JWT/JWK without explicit alg option -- algorithm confusion vulnerability (CVE-2026-22817/22818)

Medium Priority:

• Using c.req.param() / c.req.query() instead of c.req.valid() -- bypasses Zod validation
• No pagination limits on list endpoints -- returns massive datasets
• Generating spec at runtime instead of build time -- wasted CPU per request
• Not returning proper status codes -- always specify (200, 404, 500)
• Wildcard CORS ("*") with credentials: true -- browsers reject this (spec violation)

Gotchas & Edge Cases:

• c.req.valid("param") uses singular "param", not "params" -- easy to mistype
• In-memory rate limiting doesn't work across multiple instances -- use a shared store
• CORS middleware must be registered before auth middleware -- OPTIONS preflight bypasses auth
• ETags should not be used for user-specific data (generates unique ETag per user)
• RPC routes must be chained (.openapi(r1, h1).openapi(r2, h2)) for type inference -- separate calls break it
• Both client and server tsconfig.json need "strict": true for RPC type inference
• contextStorage() middleware must be registered before any code calls getContext()
• Use tryGetContext() (v4.11.0+) in code that may run outside request context (tests, background jobs)
• Middleware next() never throws in Hono -- wrapping await next() in try/catch is unnecessary
• getConnInfo is adapter-specific -- import from hono/bun, hono/deno, @hono/node-server/conninfo, etc. (NOT from hono/ip-restriction)

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(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)

Failure to follow these rules will break OpenAPI spec generation and type safety.

</critical_reminders>