index.md

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

• Getting Started
• Concepts Overview

Fundamentals

• Decorator Basics
• Request Lifecycle
• Controllers and Routes
• Request Binding
• Validation and Schemas
• Error Handling

Techniques

• Guides Overview
• Interceptors
• Middleware
• Dependency Injection
• Modules
• View Rendering
• Logging and Caller Context

Security and Contracts

• Descriptions and Metadata
• OpenAPI and Swagger
• Spec-Only Mode
• Guards and Security
• Response Validation

Reference

• Reference Overview
• Decorator Reference
• createApp Config Reference

Recipes and Operations

• Examples Index
• Production Checklist
• Publishing to Static Output
• FAQ

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],
	docs: { 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.