Bun.js + Hono + OpenAPI: документований API зі Scalar

Архітектура контракту

Схема має бути executable-документацією, а не окремим Markdown-файлом, який швидко застаріває.

Hono

Швидкий router із Web стандартами Request/Response та middleware.

Zod

Перевіряє params, query і JSON body до виконання handler-а.

OpenAPI

Формалізує endpoint-и, відповіді, помилки та security-схеми.

Scalar

Віддає зручний інтерактивний API reference для команди й інтеграторів.

Один route-контракт обслуговує запит, валідацію, OpenAPI JSON і документацію Scalar.

Крок 1: встановлення та базовий сервер

Встановіть пакети

BASH

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

Створіть OpenAPI app

import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
import { apiReference } from "@scalar/hono-api-reference";

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 }));

Підключіть документацію

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. Відкрийте /docs у браузері, а JSON-контракт доступний на /openapi.json.

Крок 2: валідація body та помилок

Описуйте не лише успішну відповідь. Клієнту потрібні стабільні схеми 400/404/500, інакше документація створює хибне відчуття типобезпеки.

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);
});

Крок 3: contract-first для клієнтів

Frontend

Використовуйте /openapi.json як джерело для генерації fetch-клієнта або типів. Це зменшує дублювання DTO.

Публічна документація

Захистіть /docs у приватному API або додайте auth middleware, якщо endpoint-и не призначені для всіх.

Версіювання

Виносьте breaking changes у /v2 або окремий документ. Не змінюйте тихо required-поля в чинній схемі.

Тести та CI

Перевіряйте OpenAPI JSON

BASH

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

Зберігайте snapshot або запускайте OpenAPI validator у CI, щоб випадково не видалити response schema.

Тестуйте через 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);
});

Типові помилки

FAQ

Часті запитання

Чим Scalar відрізняється від Swagger UI?

Обидва показують OpenAPI-документацію. Scalar — сучасний API reference UI, який легко підключити окремим маршрутом у Hono.

Чи потрібен Node.js для Hono на Bun?

Ні. Hono використовує Web API і запускається на Bun, але залежності та runtime-specific API варто перевірити у своєму deployment.

Перевірено: 27 серп. 2026 р.Актуально для: Bun 1.3+Актуально для: Hono 4.xАктуально для: Zod 4.xАктуально для: OpenAPI 3.1Актуально для: ScalarПеревірено з: Bun runtimeПеревірено з: hono/zod-validatorПеревірено з: @hono/zod-openapiПеревірено з: @scalar/hono-api-reference

Висновок

Опишіть задачу — перші 15 хвилин консультації безкоштовні.

Звʼязатися з нами Переглянути послуги та ціни

Поділитися