Hono Zod OpenAPI Middleware

1.1.1 verified Thu Apr 23 auth: no javascript

hono-zod-openapi is a middleware library for the Hono web framework that generates OpenAPI documentation directly from Zod schemas, offering a type-safe approach to API definition. Unlike some alternative solutions, it integrates as a standard Hono middleware, avoiding the need for significant refactoring of existing Hono applications. The current stable version is 1.1.1, released in February 2026. The project maintains an active release cadence, with frequent minor updates and bug fixes. Its key differentiator is the non-intrusive middleware pattern for OpenAPI definition, making it easy to adopt in existing Hono projects, along with providing a `createOpenApiDocument` function to serve the generated documentation.

Common errors

error Error: Cannot find module 'zod' or its corresponding type declarations. ↓

cause Zod is a peer dependency but not installed or is an incompatible version.

fix

Install Zod: npm install zod@^4.0.0 or yarn add zod@^4.0.0. Ensure it meets the required version for hono-zod-openapi.

error TypeError: c.req.valid is not a function ↓

cause The `c.req.valid` helper is provided by Hono's `zod-validator` middleware. While `hono-zod-openapi` helps define schemas, it doesn't automatically enable schema validation for incoming requests.

fix

You need to explicitly use Hono's validator middleware (e.g., import { validator } from '@hono/zod-validator';) on your routes to enable request validation and access c.req.valid().

error Property 'valid' does not exist on type 'Request'. ↓

cause TypeScript error indicating that the `valid` property is not recognized on the Hono `Request` object. This usually happens when the Hono context isn't correctly typed to include the validated request.

fix

Ensure you are using c.req.valid('param') etc. within a Hono handler that has the validator middleware applied and that your project is configured for TypeScript with hono and hono-zod-openapi types correctly installed.

Warnings

breaking Version 1.0.0 requires Node.js v20 or higher. Applications running on older Node.js versions will encounter compatibility issues. ↓

fix Upgrade your Node.js environment to version 20 or newer to ensure compatibility and leverage the latest features and security updates.

breaking Version 1.0.0 enforces the use of Zod v4. Projects using Zod v3 or older will need to upgrade their Zod dependency. ↓

fix Update your `zod` package to version `^4.0.0` or higher in your `package.json` and reinstall dependencies.

gotcha Hono's `.onError` middleware, if used before defining routes, might interfere with how hono-zod-openapi processes routes for documentation generation. This was addressed in v1.0.3, but ensure `.onError` is placed appropriately. ↓

fix Upgrade to `hono-zod-openapi@1.0.3` or later. If upgrading is not possible, define all your OpenAPI-enabled routes before attaching generic `.onError` handlers.

gotcha When using Hono versions 4.10.0 or higher, older versions of `hono-zod-openapi` might encounter type errors with `createOpenApiMiddleware` due to changes in Hono's typings. ↓

fix Upgrade `hono-zod-openapi` to version `1.0.2` or later to ensure type compatibility with newer Hono versions.

Install

npm install hono-zod-openapi

yarn add hono-zod-openapi

pnpm add hono-zod-openapi

Imports

openApi

wrong

import openApi from 'hono-zod-openapi';

correct

import { openApi } from 'hono-zod-openapi';

This is a named export for the core OpenAPI middleware function.

createOpenApiDocument
wrong
```
import { CreateOpenApiDocument } from 'hono-zod-openapi';
```
correct
```
import { createOpenApiDocument } from 'hono-zod-openapi';
```
This function takes the Hono app and OpenAPI info to generate and serve the documentation JSON.
defineOpenApiOperation
```
import { defineOpenApiOperation } from 'hono-zod-openapi';
```
A utility function to help define OpenAPI operations with full type inference and autocompletion.

Quickstart

This quickstart demonstrates how to define a Hono route using the `openApi` middleware, link Zod schemas for request parameters and responses, and then generate and serve the OpenAPI document and Swagger UI.

import { Hono } from 'hono';
import * as z from 'zod';
import { createOpenApiDocument, openApi, swaggerUI } from 'hono-zod-openapi';

const app = new Hono();

// Define an API endpoint with OpenAPI documentation using Zod schemas
app.get(
  '/user/:id',
  openApi({
    tags: ['User Management'],
    summary: 'Get user by ID',
    description: 'Retrieves a single user resource based on their unique ID.',
    responses: {
      200: { description: 'Successful response', content: { 'application/json': { schema: z.object({ id: z.string(), name: z.string() }) } } },
      404: { description: 'User not found' }
    },
    request: {
      params: z.object({ id: z.string().uuid('Invalid user ID format') }),
      query: z.object({ verbose: z.boolean().optional() })
    }
  }),
  (c) => {
    const { id } = c.req.valid('param');
    // In a real app, you'd fetch from a DB
    if (id === '123e4567-e89b-12d3-a456-426614174000') {
      return c.json({ id, name: 'John Doe' });
    } else {
      return c.notFound();
    }
  },
);

// Generate and serve the OpenAPI documentation at '/doc'
const document = createOpenApiDocument(app, {
  info: {
    title: 'Example Hono API',
    version: '1.0.0',
    description: 'An example API built with Hono and documented with hono-zod-openapi.'
  },
  servers: [{ url: 'http://localhost:3000', description: 'Development Server' }]
});

// Serve Swagger UI for the generated document at '/swagger'
app.get('/swagger', swaggerUI({ url: '/doc' }));

// Serve the raw OpenAPI JSON document at '/doc'
app.get('/doc', (c) => c.json(document));

export default app;