Hono OpenAPI β
hono-openapi is a middleware which enables automatic OpenAPI documentation generation for your Hono API by integrating with validation libraries like Zod, Valibot, ArkType, and TypeBox and all libs supporting Standard Schema.
π οΈ Installation β
Install the package along with your preferred validation library and its dependencies:
npm install hono-openapi @hono/standard-validator
π Getting Started β
1. Define Your Schemas β
Define your request and response schemas using your preferred validation library. Here's an example using Valibot:
import * as v from 'valibot'
const querySchema = v.object({
name: v.optional(v.string()),
})
const responseSchema = v.string()
2. Create Routes β
Use describeRoute
for route documentation and validation:
import { Hono } from 'hono'
import { describeRoute, resolver, validator } from 'hono-openapi'
const app = new Hono()
app.get(
'/',
describeRoute({
description: 'Say hello to the user',
responses: {
200: {
description: 'Successful response',
content: {
'text/plain': { schema: resolver(responseSchema) },
},
},
},
}),
validator('query', querySchema),
(c) => {
const query = c.req.valid('query')
return c.text(`Hello ${query?.name ?? 'Hono'}!`)
}
)
Note:
When usingvalidator()
fromhono-openapi
, any validation added forquery
,json
,param
orform
is automatically included in the OpenAPI request schema.
Thereβs no need to manually define request parameters insidedescribeRoute()
.
3. Generate OpenAPI Spec β
Add an endpoint for your OpenAPI document:
import { openAPIRouteHandler } from 'hono-openapi'
app.get(
'/openapi',
openAPIRouteHandler(app, {
documentation: {
info: {
title: 'Hono API',
version: '1.0.0',
description: 'Greeting API',
},
servers: [
{ url: 'http://localhost:3000', description: 'Local Server' },
],
},
})
)
Wanna explore more, check out our docs - https://honohub.dev/docs/openapi