bun-openapi Documentation

Decorator-driven OpenAPI 3.0 generation and request validation for Bun.

bun-openapi is a lightweight framework that lets you define your API with TypeScript decorators and automatically generates a valid OpenAPI 3.0 specification from those definitions. Your controllers and models become the single source of truth — no separate spec files to keep in sync.

Goal

TypeScript decorators as the single source of truth for routes, validation, and API documentation.
A valid OpenAPI 3.0 spec generated at startup from your controllers — no code generation step required.
Runtime request validation and response validation powered by your choice of schema library.
Built-in Swagger UI for instant API exploration during development.
Lightweight DI container, guards, interceptors, and middleware for production patterns.

Philosophy

Rely on decorators to express route metadata; use adapters for validation logic.
Minimize boilerplate — a controller class, a few decorators, and createApp() are all you need.
Stay close to the platform — bun-openapi targets Bun.serve directly, no compatibility layers.
Bring your own validation — class-validator, TypeBox, Zod and Valibot adapters ship out of the box.
Keep it small — the goal is a bare minimum for efficient API development, not a kitchen-sink framework.

First Steps

Fundamentals

Techniques

Security and Contracts

Reference

Recipes and Operations

Quick Example

import {
    Controller,
    createApp,
    Get,
    Returns,
    Route,
    Summary,
} from "bun-openapi";
import { classValidator } from "bun-openapi/adapters/class-validator";

class User {
    id!: string;
    name!: string;
}

@Route("/users")
class UserController extends Controller {
    @Get()
    @Summary("List users")
    @Returns(200, [User])
    list() {
        return [];
    }
}

const app = createApp({
    schema: classValidator(),
    controllers: [UserController],
    swagger: true,
    openapi: { service: { name: "my-api", version: "1.0.0" } },
});

Bun.serve({ port: 3000, routes: app.routes, fetch: app.fetch });

Open http://localhost:3000/docs/swagger/ to see your generated API docs.