{"id":17682,"library":"hono-zod-openapi","title":"Hono Zod OpenAPI Middleware","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/paolostyle/hono-zod-openapi","tags":["javascript","documentation","hono","middleware","openapi","swagger","typescript","zod"],"install":[{"cmd":"npm install hono-zod-openapi","lang":"bash","label":"npm"},{"cmd":"yarn add hono-zod-openapi","lang":"bash","label":"yarn"},{"cmd":"pnpm add hono-zod-openapi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core web framework integration; required for `Hono` application instances and middleware.","package":"hono","optional":false},{"reason":"Schema definition library; used for defining request, response, and parameter types which are then converted to OpenAPI specifications.","package":"zod","optional":false}],"imports":[{"note":"This is a named export for the core OpenAPI middleware function.","wrong":"import openApi from 'hono-zod-openapi';","symbol":"openApi","correct":"import { openApi } from 'hono-zod-openapi';"},{"note":"This function takes the Hono app and OpenAPI info to generate and serve the documentation JSON.","wrong":"import { CreateOpenApiDocument } from 'hono-zod-openapi';","symbol":"createOpenApiDocument","correct":"import { createOpenApiDocument } from 'hono-zod-openapi';"},{"note":"A utility function to help define OpenAPI operations with full type inference and autocompletion.","symbol":"defineOpenApiOperation","correct":"import { defineOpenApiOperation } from 'hono-zod-openapi';"}],"quickstart":{"code":"import { Hono } from 'hono';\nimport * as z from 'zod';\nimport { createOpenApiDocument, openApi, swaggerUI } from 'hono-zod-openapi';\n\nconst app = new Hono();\n\n// Define an API endpoint with OpenAPI documentation using Zod schemas\napp.get(\n  '/user/:id',\n  openApi({\n    tags: ['User Management'],\n    summary: 'Get user by ID',\n    description: 'Retrieves a single user resource based on their unique ID.',\n    responses: {\n      200: { description: 'Successful response', content: { 'application/json': { schema: z.object({ id: z.string(), name: z.string() }) } } },\n      404: { description: 'User not found' }\n    },\n    request: {\n      params: z.object({ id: z.string().uuid('Invalid user ID format') }),\n      query: z.object({ verbose: z.boolean().optional() })\n    }\n  }),\n  (c) => {\n    const { id } = c.req.valid('param');\n    // In a real app, you'd fetch from a DB\n    if (id === '123e4567-e89b-12d3-a456-426614174000') {\n      return c.json({ id, name: 'John Doe' });\n    } else {\n      return c.notFound();\n    }\n  },\n);\n\n// Generate and serve the OpenAPI documentation at '/doc'\nconst document = createOpenApiDocument(app, {\n  info: {\n    title: 'Example Hono API',\n    version: '1.0.0',\n    description: 'An example API built with Hono and documented with hono-zod-openapi.'\n  },\n  servers: [{ url: 'http://localhost:3000', description: 'Development Server' }]\n});\n\n// Serve Swagger UI for the generated document at '/swagger'\napp.get('/swagger', swaggerUI({ url: '/doc' }));\n\n// Serve the raw OpenAPI JSON document at '/doc'\napp.get('/doc', (c) => c.json(document));\n\nexport default app;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer to ensure compatibility and leverage the latest features and security updates.","message":"Version 1.0.0 requires Node.js v20 or higher. Applications running on older Node.js versions will encounter compatibility issues.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Update your `zod` package to version `^4.0.0` or higher in your `package.json` and reinstall dependencies.","message":"Version 1.0.0 enforces the use of Zod v4. Projects using Zod v3 or older will need to upgrade their Zod dependency.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.3"},{"fix":"Upgrade `hono-zod-openapi` to version `1.0.2` or later to ensure type compatibility with newer Hono versions.","message":"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.","severity":"gotcha","affected_versions":"<1.0.2"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"Zod is a peer dependency but not installed or is an incompatible version.","error":"Error: Cannot find module 'zod' or its corresponding type declarations."},{"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()`.","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.","error":"TypeError: c.req.valid is not a function"},{"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.","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.","error":"Property 'valid' does not exist on type 'Request'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}