Bun.js + Hono + OpenAPI: eine dokumentierte API mit Scalar

Die Vertragsarchitektur

Ein ausführbarer Vertrag ist zuverlässiger als ein Markdown-Dokument, das langsam veraltet.

Hono

Ein schneller Router auf Basis der Web-Request- und Response-APIs.

Zod

Validiert Parameter, Query und JSON vor dem Handler.

OpenAPI

Formalisierte Endpunkte, Antworten, Fehler und Security-Schemas.

Scalar

Interaktive API-Referenz für Teams und Integratoren.

Ein Route-Vertrag steuert Request, Validierung, OpenAPI-JSON und Scalar-Dokumentation.

Schritt 1: Installation und Server

Pakete installieren

BASH

bun init
bun add hono @hono/zod-openapi zod @scalar/hono-api-reference

OpenAPI-App erstellen

import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
const app = new OpenAPIHono();
const task = z.object({ id: z.string(), title: z.string(), done: z.boolean() });
const route = createRoute({ method: "get", path: "/tasks/{id}", request: { params: z.object({ id: z.string().uuid() }) }, responses: { 200: { content: { "application/json": { schema: task } }, description: "A task" } } });
app.openapi(route, (c) => c.json({ id: c.req.valid("param").id, title: "Read docs", done: false }));

Dokumentation veröffentlichen

app.doc("/openapi.json", { openapi: "3.1.0", info: { title: "Tasks API", version: "1.0.0" } });
app.get("/docs", apiReference({ spec: { url: "/openapi.json" } }));
export default { port: Number(Bun.env.PORT ?? 3000), fetch: app.fetch };

bun run src/index.ts starten. /docs öffnet die UI, /openapi.json den Vertrag.

Schritt 2: Body und Fehler validieren

Dokumentiere nicht nur den Happy Path. Stabile 400-, 404- und 500-Schemas gehören zum API-Vertrag.

const createTask = createRoute({ method: "post", path: "/tasks", request: { body: { content: { "application/json": { schema: z.object({ title: z.string().trim().min(1).max(120) }) } } } }, responses: { 201: { content: { "application/json": { schema: task } }, description: "Created" }, 422: { content: { "application/json": { schema: z.object({ error: z.string() }) } }, description: "Validation error" } } });
app.openapi(createTask, async (c) => { const body = c.req.valid("json"); return c.json({ id: crypto.randomUUID(), title: body.title, done: false }, 201); });

Schritt 3: Contract-first-Clients

Frontend

Generiere Client oder Typen aus /openapi.json, statt DTOs zu duplizieren.

Öffentliche Docs

Schütze /docs mit Auth, wenn die API privat ist.

Versionierung

Breaking Changes gehören nach /v2 oder in ein neues Dokument.

Tests und CI

OpenAPI JSON prüfen

BASH

curl http://localhost:3000/openapi.json

Snapshot oder OpenAPI-Validator in CI verwenden.

Mit app.fetch testen

import { expect, test } from "bun:test";
import app from "./index";
test("lehnt ungültige ID ab", async () => { const response = await app.fetch(new Request("http://localhost/tasks/nope")); expect(response.status).toBe(400); });

Häufige Fehler

FAQ

Wie unterscheidet sich Scalar von Swagger UI?

Beide rendern OpenAPI-Dokumentation. Scalar ist eine moderne API-Referenz, die einfach als Hono-Route eingebunden wird.

Braucht Hono Node.js auf Bun?

Nein. Hono nutzt Web-APIs und läuft auf Bun. Runtime-spezifische Dependencies sollten trotzdem im Deployment getestet werden.

Geprüft: 27. Aug. 2026Gilt für: Bun 1.3+Gilt für: Hono 4.xGilt für: Zod 4.xGilt für: OpenAPI 3.1Gilt für: ScalarGetestet mit: Bun runtimeGetestet mit: hono/zod-validatorGetestet mit: @hono/zod-openapiGetestet mit: @scalar/hono-api-reference

Fazit

Beschreiben Sie die Aufgabe — die ersten 15 Minuten der Beratung sind kostenlos.

Kontakt aufnehmen Services und Preise ansehen