Hono 文档

¥Hono Docs

从 Hono 路由类型定义自动生成 OpenAPI 3.0 规范和 TypeScript 类型快照。

¥Auto-generate OpenAPI 3.0 spec and TypeScript type snapshots from Hono route type definitions

Hono 文档 为 Hono 提供自动生成的 OpenAPI 文档。

¥Hono Docs provides auto generated OpenApi Docs for Hono.

在项目根目录 (hono-docs.ts) 创建配置文件

¥Create a config file at the root of your project (hono-docs.ts)

import { defineConfig } from '@rcmade/hono-docs'

export default defineConfig({
  tsConfigPath: './tsconfig.json',
  openApi: {
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
    servers: [{ url: 'http://localhost:3000/api' }],
  },
  outputs: {
    openApiJson: './openapi/openapi.json',
  },
  apis: [
    {
      name: 'Auth Routes',
      apiPrefix: '/auth', // This will be prepended to all `api` values below
      appTypePath: 'src/routes/authRoutes.ts', // Path to your AppType export

      api: [
        // ✅ Custom OpenAPI metadata for the GET /auth/u/{id} endpoint
        {
          api: '/u/{id}', // Final route = /auth/u/{id}
          method: 'get',
          summary: 'Fetch user by ID', // Optional: title shown in docs
          description:
            'Returns a user object based on the provided ID.',
          tag: ['User'],
        },

        // ✅ Another example with metadata for GET /auth
        {
          api: '/', // Final route = /auth/
          method: 'get',
          summary: 'Get current user',
          description:
            "Returns the currently authenticated user's information.",
          tag: ['User Info'],
        },
      ],
    },
  ],
})

路由定义和应用类型

¥Route Definitions & AppType

此库仅支持通过在路由文件中导出单个 AppType 来更改路由。你必须导出：

¥This library supports only change routes via a single AppType export in your routes file. You must export:

export type AppType = typeof yourRoutesVariable

示例：

¥Example:

// src/routes/userRoutes.ts
import { Hono } from 'hono'
import { z } from 'zod'

export const userRoutes = new Hono()
  .get('/u/:id', (c) => {
    /* … */
  })
  .post('/', async (c) => {
    /* … */
  })
// Must add AppType
export type AppType = typeof userRoutes
export default userRoutes

在你的 Hono 应用中挂载：

¥Mount in your Hono app:

// src/routes/docs.ts
import { Hono } from 'hono'
import { Scalar } from '@scalar/hono-api-reference'
import fs from 'node:fs/promises'
import path from 'node:path'

const docs = new Hono()
  .get(
    '/',
    Scalar({
      url: '/api/docs/open-api',
      theme: 'kepler',
      layout: 'modern',
      defaultHttpClient: { targetKey: 'js', clientKey: 'axios' },
    })
  )
  .get('/open-api', async (c) => {
    const raw = await fs.readFile(
      path.join(process.cwd(), './openapi/openapi.json'),
      'utf-8'
    )
    return c.json(JSON.parse(raw))
  })

export type AppType = typeof docs
export default docs

访问 /api/docs 可查看用户界面；/api/docs/open-api 提供 JSON 数据。

¥Visiting /api/docs shows the UI; /api/docs/open-api serves the JSON.

创建配置后，使用以下命令生成 spec：

¥After you’ve created your config, generate the spec with:

npx @rcmade/hono-docs generate --config ./hono-docs.ts

CLI 使用方法

¥CLI Usage

Usage: @rcmade/hono-docs generate --config <your hono-docs.ts path (default root/hono-docs.ts)>

Options:
  -c, --config   Path to your config file (TS or JS)        [string] [required]
  -h, --help     Show help                                 [boolean]

示例

¥Examples

查看 examples/basic-app/ 以了解最小设置。

¥Check out examples/basic-app/ for a minimal setup.