Registry / web-framework / hono-zod-openapi

hono-zod-openapi

library1.1.1jsnpmunverified

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.

web-framework serialization

npm install hono-zod-openapi

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HONO-ZOD-OPENAPI

hono-zod-openapi

web-frameworkjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

openApi

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

✗ import openApi from 'hono-zod-openapi';

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

createOpenApiDocument

✓ import { createOpenApiDocument } from 'hono-zod-openapi';

✗ 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.

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;

Debug

Known issues

breakingVersion 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.

affects: >=1.0.0

breakingVersion 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.

affects: >=1.0.0

gotchaHono'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.

affects: <1.0.3

gotchaWhen 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.

affects: <1.0.2

Errors

Common errors & fixes

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

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.

TypeError: c.req.valid is not a function

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

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

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.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

honorequiredCore web framework integration; required for `Hono` application instances and middleware.

zodrequiredSchema definition library; used for defining request, response, and parameter types which are then converted to OpenAPI specifications.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/paolostyle/hono-zod-openapi ↗

packagehttps://www.npmjs.com/package/hono-zod-openapi ↗

homepagehttps://hono-zod-openapi.pages.dev ↗