Hono OpenAPI

hono-openapi ist eine Middleware, die durch die Integration von Validierungsbibliotheken wie Zod, Valibot, ArkType und TypeBox sowie allen Bibliotheken mit Unterstützung für Standard Schema automatisch OpenAPI-Dokumentation für deine Hono-API erzeugt.

🛠️ Installation

Installiere das Paket zusammen mit deiner bevorzugten Validierungsbibliothek und deren Abhängigkeiten:

npm install hono-openapi @hono/standard-validator

In dieser Anleitung verwenden wir valibot.

npm install valibot @valibot/to-json-schema

Weitere Informationen zur Installation findest du hier: https://honohub.dev/docs/openapi#installation

---

🚀 Erste Schritte

1. Schemas definieren

Definiere die Schemas für Anfragen und Antworten mit deiner bevorzugten Validierungsbibliothek. Hier ist ein Beispiel mit Valibot:

import * as v from 'valibot'

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

const responseSchema = v.string()

---

2. Routen erstellen

Verwende describeRoute für die Routendokumentation und Validierung:

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'}!`)
  }
)

Hinweis:
Wenn du validator() aus hono-openapi verwendest, werden Validierungen für query, json, param oder form automatisch in das OpenAPI-Anfrageschema aufgenommen.
Du musst die Anfrageparameter nicht manuell in describeRoute() definieren.

---

3. OpenAPI-Spezifikation generieren

Füge einen Endpunkt für dein OpenAPI-Dokument hinzu:

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' },
      ],
    },
  })
)

---

Weitere Informationen findest du in unserer Dokumentation: https://honohub.dev/docs/openapi