Bun.js + Hono + OpenAPI: a documented API with Scalar

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.

Step 1: install and create the server

Install packages

BASH

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

Create 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

BASH

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

Use 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

How is Scalar different from Swagger UI?

Both render OpenAPI documentation. Scalar is a modern API reference UI that can be mounted as a Hono route.

Does Hono require Node.js on Bun?

No. Hono uses Web APIs and runs on Bun, but always test runtime-specific dependencies in deployment.

Reviewed: 27 Aug 2026Applies to: Bun 1.3+Applies to: Hono 4.xApplies to: Zod 4.xApplies to: OpenAPI 3.1Applies to: ScalarTested with: Bun runtimeTested with: hono/zod-validatorTested with: @hono/zod-openapiTested with: @scalar/hono-api-reference

Conclusion

Describe the task — first 15 minutes of consultation are free.