Hono OpenAPI

hono-openapi 是一个 中间件，通过与诸如 Zod、Valibot、ArkType 和 TypeBox 等验证库集成，为你的 Hono API 启用自动 OpenAPI 文档生成。

🛠️ 安装

安装此包以及你偏好的验证库及其依赖项：

# 对于 Zod
pnpm add hono-openapi @hono/zod-validator zod zod-openapi

# 对于 Valibot
pnpm add hono-openapi @hono/valibot-validator valibot @valibot/to-json-schema

# 对于 ArkType
pnpm add hono-openapi @hono/arktype-validator arktype

# 对于 TypeBox
pnpm add hono-openapi @hono/typebox-validator @sinclair/typebox

---

🚀 快速开始

1. 定义你的 Schema

使用你偏好的验证库定义你的请求和响应 schema。这是一个使用 Valibot 的示例：

import * as v from 'valibot'

const querySchema = v.object({
  name: v.optional(v.string()),
})

const responseSchema = v.string()

---

2. 创建路由

使用 describeRoute 进行路由文档记录和验证：

import { Hono } from 'hono'
import { describeRoute } from 'hono-openapi'
// 你可以为偏好的验证库导入这些
import {
  resolver,
  validator as vValidator,
} from 'hono-openapi/valibot'

const app = new Hono()

app.get(
  '/',
  describeRoute({
    description: '向用户问好',
    responses: {
      200: {
        description: '成功响应',
        content: {
          'text/plain': { schema: resolver(responseSchema) },
        },
      },
    },
  }),
  vValidator('query', querySchema),
  (c) => {
    const query = c.req.valid('query')
    return c.text(`Hello ${query?.name ?? 'Hono'}!`)
  }
)

---

3. 生成 OpenAPI Spec

为你的 OpenAPI 文档添加一个端点：

import { openAPISpecs } from 'hono-openapi'

app.get(
  '/openapi',
  openAPISpecs(app, {
    documentation: {
      info: {
        title: 'Hono API',
        version: '1.0.0',
        description: 'Greeting API',
      },
      servers: [
        { url: 'http://localhost:3000', description: '本地服务器' },
      ],
    },
  })
)

---

🌐 提供 API 文档服务

使用诸如 Swagger UI 或 Scalar 等工具来可视化你的 OpenAPI spec。 这是一个使用 Scalar 的示例：

import { apiReference } from '@scalar/hono-api-reference'

app.get(
  '/docs',
  apiReference({
    theme: 'saturn',
    spec: { url: '/openapi' },
  })
)

---

🔍 高级功能

添加安全定义

app.get(
  '/openapi',
  openAPISpecs(app, {
    documentation: {
      components: {
        securitySchemes: {
          bearerAuth: {
            type: 'http',
            scheme: 'bearer',
            bearerFormat: 'JWT',
          },
        },
      },
      security: [{ bearerAuth: [] }],
    },
  })
)

有条件地隐藏路由

app.get(
  '/',
  describeRoute({
    // ...
    hide: process.env.NODE_ENV === 'production',
  }),
  (c) => c.text('Hidden Route')
)

验证响应

app.get(
  '/',
  describeRoute({
    // ...
    validateResponse: true,
  }),
  (c) => c.text('Validated Response')
)

---

你可以在 hono-openapi 仓库 中找到更多示例和详细文档。