docs: update guides and add descriptions and metadata section

Author: xseman

docs/concepts/decorators.md

@@ -2,46 +2,67 @@
 
 [Docs Home](../index.md) | [Previous: Getting Started](../getting-started.md) | [Next: Request Lifecycle](request-lifecycle.md)
 
-Decorators define routes, validation, metadata, and runtime behavior. bun-openapi reads decorator metadata at startup and builds:
+Decorators are the primary way you configure bun-openapi. Instead of writing separate route registration code and OpenAPI spec files, you annotate your controller classes — and the framework reads that metadata at startup to build:
 
-- Bun route handlers
-- runtime validation wiring
-- OpenAPI document
+- **Bun route handlers** with parameter binding and validation.
+- **Runtime behavior** — guards, interceptors, and middleware execution order.
+- **OpenAPI 3.0 document** with paths, schemas, security, and response descriptions.
+
+This means your TypeScript code is the single source of truth for both the running server and the API documentation.
 
 ## Class-Level Decorators
 
-- @Route("/prefix") sets the base path.
-- @Tags("Users") sets OpenAPI tags for all methods.
-- @Security("bearerAuth") applies default security requirements.
-- @UseGuards(...) attaches guards to all controller methods.
-- @UseInterceptors(...) attaches interceptors to all methods.
-- @ValidateResponse(true) enables response validation by default.
-- @Middleware(...) adds middleware wrappers at controller scope.
+These decorators go on your controller class and affect all methods within it.
+
+| Decorator                 | Effect                                       |
+| ------------------------- | -------------------------------------------- |
+| `@Route("/prefix")`       | Sets the base path for all endpoints         |
+| `@Tags("Users")`          | Applies OpenAPI tags to all methods          |
+| `@Security("bearerAuth")` | Adds default security requirement            |
+| `@UseGuards(...)`         | Attaches guards to all methods               |
+| `@UseInterceptors(...)`   | Attaches interceptors to all methods         |
+| `@ValidateResponse(true)` | Enables response validation by default       |
+| `@Middleware(...)`        | Adds middleware wrappers at controller scope |
 
 ## Method-Level Decorators
 
-- HTTP verbs: @Get, @Post, @Put, @Patch, @Delete
-- OpenAPI metadata: @Summary, @Description, @OperationId, @Deprecated, @Hidden
-- Response metadata: @Returns(status, schema, description), @Produces(contentType)
-- Runtime behavior: @UseGuards, @UseInterceptors, @ValidateResponse, @Render
+These decorators go on individual methods to define endpoints and their behavior.
+
+- **HTTP verbs**: `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`
+- **OpenAPI metadata**: `@Summary`, `@Description`, `@OperationId`, `@Deprecated`, `@Hidden`
+- **Response metadata**: `@Returns(status, schema, description)`, `@Produces(contentType)`
+- **Runtime behavior**: `@UseGuards`, `@UseInterceptors`, `@ValidateResponse`, `@Render`, `@Security`
+
+> **TIP**: Method-level decorators override class-level ones where it makes sense. For example, `@Security` on a method replaces the controller-level security requirement for that specific endpoint.
 
 ## Parameter Decorators
 
-- @Param(schema) or @Param("id")
-- @Query(schema) or @Query("page")
-- @Header(schema) or @Header("x-request-id")
-- @Body(schema)
-- @Request()
+These bind incoming request data to method arguments. They come in two flavors:
+
+- **Whole-object**: pass a schema class for validation — `@Param(UserParams)`, `@Body(CreateUser)`
+- **Scalar**: pass a string name for single values — `@Param("id")`, `@Query("page")`
+
+| Decorator         | Source          |
+| ----------------- | --------------- |
+| `@Param(schema)`  | Path parameters |
+| `@Query(schema)`  | Query string    |
+| `@Header(schema)` | Request headers |
+| `@Body(schema?)`  | Request body    |
+| `@Request()`      | Raw `Request`   |
 
 ## Mental Model
 
-Think in layers:
+Think of decorators as defining layers that compose at startup:
+
+```
+@Route + @Get/@Post/...       →  1. Route matching
+@Param/@Query/@Body/...       →  2. Parameter binding & validation
+@UseGuards / @Security        →  3. Guard & security checks
+@UseInterceptors              →  4. Interceptor wrapping
+                              →  5. Controller method execution
+@Returns + @ValidateResponse  →  6. Optional response validation
+```
 
-1. Route matching from @Route + verb decorators.
-2. Parameter binding and validation from parameter decorators.
-3. Guards and security checks.
-4. Interceptor wrapping.
-5. Controller execution.
-6. Optional response validation.
+Each layer reads metadata that you declared with decorators. No manual wiring required.
 
-Continue with [Request Lifecycle](request-lifecycle.md) for exact execution order.
+Continue with [Request Lifecycle](request-lifecycle.md) for the exact execution order at runtime.

docs/getting-started.md

@@ -2,29 +2,35 @@
 
 [Docs Home](index.md) | [Next: Decorator Basics](concepts/decorators.md)
 
+This guide walks you through building a small Users API with bun-openapi. By the end you will have a running Bun server with automatic request validation, a generated OpenAPI 3.0 spec, and live Swagger UI.
+
+> **Prerequisites**: [Bun](https://bun.sh/) >= 1.0 installed.
+
 ## Install
 
-Install bun-openapi and one schema adapter.
+Install bun-openapi and one schema adapter. This guide uses `class-validator`, but you can swap it for TypeBox, Zod, or Valibot later.
 
 ```sh
 bun add bun-openapi class-validator
 ```
 
-## 1) Create a Controller
+## 1) Define a Model
+
+Start by defining the data shapes your API will use. These classes serve double duty — they are TypeScript types for your code **and** the source for OpenAPI schema definitions.
 
 ```ts
 import {
-	Body,
-	Controller,
-	Get,
-	Post,
-	Returns,
-	Route,
-	Summary,
-} from "bun-openapi";
+	IsEmail,
+	IsString,
+	MinLength,
+} from "class-validator";
 
 class CreateUser {
+	@IsString()
+	@MinLength(1)
 	name!: string;
+
+	@IsEmail()
 	email!: string;
 }
 
@@ -33,6 +39,24 @@ class User {
 	name!: string;
 	email!: string;
 }
+```
+
+> **TIP**: With `class-validator`, you can add validation constraints directly on the DTO fields. These constraints are enforced at runtime and also appear in the generated OpenAPI spec.
+
+## 2) Create a Controller
+
+Controllers define your routes. The `@Route` decorator sets the base path, and HTTP-verb decorators (`@Get`, `@Post`, ...) register individual endpoints. Parameter decorators like `@Body` bind and validate incoming data automatically.
+
+```ts
+import {
+	Body,
+	Controller,
+	Get,
+	Post,
+	Returns,
+	Route,
+	Summary,
+} from "bun-openapi";
 
 @Route("/users")
 class UserController extends Controller {
@@ -57,7 +81,20 @@ class UserController extends Controller {
 }
 ```
 
-## 2) Start Bun Server
+Let's break down what's happening:
+
+- `@Route("/users")` sets `/users` as the base path for all methods in this class.
+- `@Get()` combined with the base route creates a `GET /users` endpoint.
+- `@Post()` creates `POST /users`.
+- `@Summary(...)` becomes the endpoint summary in generated OpenAPI docs.
+- `@Returns(201, User, ...)` tells bun-openapi what the success response looks like — both for documentation and optional response validation.
+- `@Body(CreateUser)` validates the incoming JSON body against the `CreateUser` schema before the method executes.
+
+> **TIP**: If validation fails (e.g. a missing `name` field), the framework automatically returns a 400 error with details. You don't need to write any validation logic yourself.
+
+## 3) Start the Server
+
+Wire everything together with `createApp()` and pass the result to `Bun.serve`:
 
 ```ts
 import { createApp } from "bun-openapi";
@@ -82,16 +119,33 @@ Bun.serve({
 });
 ```
 
-## 3) Open Generated Docs
+`createApp()` does several things at startup:
+
+1. Reads decorator metadata from your controllers.
+2. Builds a Bun route map with validation, guards, and interceptors wired in.
+3. Generates an OpenAPI 3.0 document from the collected metadata.
+4. Optionally serves Swagger UI and the raw spec.
+
+## 4) Open Generated Docs
+
+Start your server and visit:
+
+- **Swagger UI**: [http://localhost:3000/docs/swagger/](http://localhost:3000/docs/swagger/)
+- **OpenAPI JSON**: [http://localhost:3000/docs/swagger/openapi.json](http://localhost:3000/docs/swagger/openapi.json)
+
+You should see your `Users` endpoints listed with their request/response schemas — all generated from the decorators you wrote. Try sending a `POST /users` with an invalid body to see validation in action.
 
-- Swagger UI: /docs/swagger/
-- OpenAPI JSON: /docs/swagger/openapi.json
+## What's Next?
 
-## What To Read Next
+Now that you have a running API, explore deeper topics:
 
-- [Decorator Basics](concepts/decorators.md)
-- [Request Binding](guides/request-binding.md)
-- [Validation and Schemas](guides/validation-and-schemas.md)
+- **[Decorator Basics](concepts/decorators.md)** — understand the full decorator model and how layers compose.
+- **[Request Binding](guides/request-binding.md)** — learn about `@Param`, `@Query`, `@Header`, and scalar vs. whole-object binding.
+- **[Validation and Schemas](guides/validation-and-schemas.md)** — swap adapters, add constraints, and understand how validation integrates with OpenAPI.
+- **[Error Handling](guides/error-handling.md)** — customize error responses with `errorFormatter` and built-in exceptions.
+- **[Dependency Injection](guides/dependency-injection.md)** — organize code with providers and service classes.
+- **[Guards and Security](guides/guards-and-security.md)** — add authentication and authorization to your endpoints.
+- **[Descriptions and Metadata](guides/descriptions-and-metadata.md)** — enrich your OpenAPI docs with summaries, descriptions, and operation IDs.
 
 ## Runnable Example
 

docs/guides/controllers-and-routes.md

@@ -2,7 +2,7 @@
 
 [Docs Home](../index.md) | [Previous: Request Lifecycle](../concepts/request-lifecycle.md) | [Next: Request Binding](request-binding.md)
 
-Use Controller subclasses with route decorators to define endpoints.
+Controllers are the core building block in bun-openapi. Each controller is a class that extends `Controller` and uses decorators to define its routes. At startup, `createApp()` reads this metadata and builds both Bun route handlers and the OpenAPI specification.
 
 ## Basic Pattern
 
@@ -29,28 +29,59 @@ class ProjectController extends Controller {
 }
 ```
 
+The `@Route("/projects")` decorator sets `/projects` as the base path. `@Get()` and `@Post()` register `GET /projects` and `POST /projects` respectively. The return value is automatically serialized as JSON.
+
 ## Path Joining Rules
 
-- Controller prefix comes from @Route.
-- Method path comes from verb decorator argument.
-- Trailing slash aliases are handled for registered routes.
+The final path for each endpoint is constructed by joining the controller prefix with the method path:
+
+| `@Route` | Verb decorator   | Resulting path     |
+| -------- | ---------------- | ------------------ |
+| `/users` | `@Get()`         | `GET /users`       |
+| `/users` | `@Get("/:id")`   | `GET /users/:id`   |
+| `/users` | `@Post("/bulk")` | `POST /users/bulk` |
+
+> **TIP**: Path parameters use the `:name` syntax (e.g. `/:id`). These map to `{id}` in the generated OpenAPI spec and can be bound with `@Param("id")` or `@Param(schema)`.
 
 ## OpenAPI Metadata
 
 Add method decorators to enrich generated operations:
 
-- @Summary
-- @Description
-- @OperationId
-- @Tags
-- @Deprecated
-- @Hidden
+- `@Summary("...")` — short one-liner shown as endpoint title.
+- `@Description("...")` — longer explanation shown when expanded.
+- `@OperationId("...")` — stable identifier for SDK generators.
+- `@Tags("...")` — groups endpoints in Swagger UI.
+- `@Deprecated()` — marks the endpoint as deprecated.
+- `@Hidden()` — excludes the endpoint from the OpenAPI spec entirely.
+
+See [Descriptions and Metadata](descriptions-and-metadata.md) for detailed examples.
 
 ## Choosing Response Status
 
-Call this.setStatus(code) before returning to set a non-default status.
+By default, successful responses return status 200. Call `this.setStatus(code)` before returning to set a different status:
+
+```ts
+@Post()
+@Returns(201, Project, "Created")
+create(@Body(CreateProject) body: CreateProject) {
+	this.setStatus(201);
+	return { id: crypto.randomUUID(), ...body };
+}
+```
+
+## Multiple Controllers
+
+Pass multiple controller classes to `createApp()`. Each controller manages its own route prefix:
+
+```ts
+const app = createApp({
+	schema: classValidator(),
+	controllers: [UserController, ProjectController, HealthController],
+});
+```
 
 ## See Also
 
+- [Descriptions and Metadata](descriptions-and-metadata.md) — making your API docs richer.
 - [examples/basic/controller.ts](https://github.com/xseman/bun-openapi/blob/master/examples/basic/controller.ts)
 - [examples/multi-controller/controllers.ts](https://github.com/xseman/bun-openapi/blob/master/examples/multi-controller/controllers.ts)