Bun.js + Hono + OpenAPI: a documented API with Scalar
Build a lightweight Bun.js API with Hono, Zod validation, OpenAPI contracts, and interactive Scalar documentation.
Hono routes requests on Bun, Zod validates payloads, OpenAPI describes the contract, and Scalar renders interactive documentation. Keeping these layers aligned prevents frontend and backend drift.
The contract architecture
An executable schema is more reliable than a Markdown document that slowly becomes outdated.
Hono
A fast router based on Web Request and Response APIs.
Zod
Validates params, query, and JSON before a handler runs.
OpenAPI
Formalizes endpoints, responses, errors, and security schemes.
Scalar
Provides an interactive API reference for teams and integrators.
One route contract powers the request, validation, OpenAPI JSON, and Scalar documentation.
Section architecture screenshotStep 1: install and create the server
Install packages
bun init
bun add hono @hono/zod-openapi zod @scalar/hono-api-referenceCreate an OpenAPI app
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 }));Expose documentation
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 };Run bun run src/index.ts. Open /docs for the UI and /openapi.json for the contract.
Step 2: validate bodies and errors
Document more than the happy path. Stable 400, 404, and 500 schemas are part of a useful API contract.
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); });Step 3: use contract-first clients
Frontend
Generate a fetch client or types from /openapi.json instead of duplicating DTOs.
Public docs
Protect /docs with auth when the API is private; documentation can reveal internal endpoints.
Versioning
Move breaking changes to /v2 or a new document instead of silently changing required fields.
Tests and CI
Check the OpenAPI JSON
curl http://localhost:3000/openapi.jsonUse a snapshot or an OpenAPI validator in CI.
Test with app.fetch
import { expect, test } from "bun:test";
import app from "./index";
test("rejects invalid task id", async () => { const response = await app.fetch(new Request("http://localhost/tasks/nope")); expect(response.status).toBe(400); });Common mistakes
FAQ
Both render OpenAPI documentation. Scalar is a modern API reference UI that can be mounted as a Hono route.
No. Hono uses Web APIs and runs on Bun, but always test runtime-specific dependencies in deployment.
Conclusion
Describe the task — first 15 minutes of consultation are free.
Related Articles
How to Add Mau Saver to a Telegram Group and Save Media in Chat
A practical guide to adding Mau Saver to a Telegram group and downloading videos, audio, and posts directly in the chat.
How to Advertise to an International Telegram Media Audience
A practical guide for advertisers: reach an international Telegram audience through Mau Saver Bot, group placements, pinned posts, and native media integrations.
AI Assistant Development Cost in 2026: RAG Chatbots, CRM Integrations, Guardrails, and Support
A practical buyer guide to AI assistant development cost in 2026: prototypes, RAG chatbots, knowledge-base assistants, CRM and website integrations, guardrails, evaluations, monitoring, and support.
AI Can Make More. Not Better: What Game Development Research Actually Says
Generative AI is entering game production, but the evidence is more nuanced than the hype. We examine developer adoption, player reception, quality risks, and a practical production model for using AI without outsourcing taste.