Technologie27. Aug. 2026·3 Min. Lesezeit·Aktualisiert 27. Aug. 2026

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

Eine leichte Bun.js-API mit Hono, Zod-Validierung, OpenAPI-Vertrag und interaktiver Scalar-Dokumentation.

TypeScript-EntwicklerPublic-API-TeamsFrontend- und Backend-Teams

Hono routet Requests auf Bun, Zod validiert Payloads, OpenAPI beschreibt den Vertrag und Scalar rendert eine interaktive Dokumentation. So bleiben Frontend und Backend synchron.

—Ein Vertrag dient Runtime, Menschen und Client-Generatoren.

—Die Dokumentation ändert sich mit dem Route-Code.

—Hono bleibt klein und eignet sich für Edge-ähnliche APIs.

X in

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