Hono Docs

OpenAPI-3.0-Spezifikation und TypeScript-Typsnapshots automatisch aus Hono-Routentypdefinitionen generieren

Hono Docs stellt automatisch erzeugte OpenAPI-Dokumentation für Hono bereit.

Konfigurationsdatei erstellen im Stammverzeichnis deines Projekts (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'],
        },
      ],
    },
  ],
})

Routendefinitionen und AppType

Diese Bibliothek unterstützt die Aktualisierung nur geänderter Routen über einen einzelnen AppType-Export in deiner Routendatei. Du musst Folgendes exportieren:

export type AppType = typeof yourRoutesVariable

Beispiel:

// src/routes/userRoutes.ts
import { Hono } from 'hono'
import * as 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

Binde dies in deine Hono-Anwendung ein:

// 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

Unter /api/docs wird die Benutzeroberfläche angezeigt; /api/docs/open-api liefert das JSON.

Nachdem du deine Konfiguration erstellt hast, generiere die Spezifikation mit:

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

CLI-Verwendung

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]

Beispiele

Eine minimale Einrichtung findest du in examples/basic-app/.