docs: update examples & docs

docs/concepts/request-lifecycle.md

@@ -39,4 +39,4 @@ bun-openapi stores endpoint metadata in async local storage:
 
 Use getCallerContext() in logging and metrics helpers to label output without manually passing method names.
 
-Example usage is available in [examples/logging/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/logging/server.ts).
+Example usage is available in [examples/08_logging/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/08_logging/server.ts).

docs/examples/index.md

@@ -2,25 +2,28 @@
 
 [Docs Home](../index.md) | [Previous: createApp Config Reference](../reference/create-app-config.md) | [Next: Production Checklist](../production-checklist.md)
 
-Runnable examples are under the repository examples directory.
+Runnable examples are under the repository `examples/` directory. They are numbered in order of increasing complexity.
 
-| Example                                                                                                  | Focus                                              |
-| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| [basic](https://github.com/xseman/bun-openapi/tree/master/examples/basic/)                               | CRUD, exceptions, Swagger UI, error formatter      |
-| [class-validator](https://github.com/xseman/bun-openapi/tree/master/examples/class-validator/)           | DTO validation with class-validator                |
-| [complex](https://github.com/xseman/bun-openapi/tree/master/examples/complex/)                           | Multi-module composition                           |
-| [dependency-injection](https://github.com/xseman/bun-openapi/tree/master/examples/dependency-injection/) | Providers, token injection, and service decorators |
-| [guards](https://github.com/xseman/bun-openapi/tree/master/examples/guards/)                             | Guards, security guard mapping, role checks        |
-| [interceptors](https://github.com/xseman/bun-openapi/tree/master/examples/interceptors/)                 | Response transformation and short-circuiting       |
-| [logging](https://github.com/xseman/bun-openapi/tree/master/examples/logging/)                           | AsyncLocalStorage request context and caller tags  |
-| [modules](https://github.com/xseman/bun-openapi/tree/master/examples/modules/)                           | Module imports/exports and visibility              |
-| [multi-controller](https://github.com/xseman/bun-openapi/tree/master/examples/multi-controller/)         | Multiple controllers and metadata decorators       |
-| [mvc](https://github.com/xseman/bun-openapi/tree/master/examples/mvc/)                                   | Server-side rendering with @Render                 |
-| [security](https://github.com/xseman/bun-openapi/tree/master/examples/security/)                         | OpenAPI security + protected endpoints             |
+| Example                                                                                                        | Focus                                                             |
+| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [01_hello-world](https://github.com/xseman/bun-openapi/tree/master/examples/01_hello-world/)                   | Minimal single-route server                                       |
+| [02_crud](https://github.com/xseman/bun-openapi/tree/master/examples/02_crud/)                                 | CRUD endpoints, DTOs, exceptions, Swagger UI, error formatter     |
+| [03_multi-controller](https://github.com/xseman/bun-openapi/tree/master/examples/03_multi-controller/)         | Multiple controllers and metadata decorators                      |
+| [04_dependency-injection](https://github.com/xseman/bun-openapi/tree/master/examples/04_dependency-injection/) | Providers, token injection, and service decorators                |
+| [05_modules](https://github.com/xseman/bun-openapi/tree/master/examples/05_modules/)                           | Module imports/exports and visibility                             |
+| [06_guards](https://github.com/xseman/bun-openapi/tree/master/examples/06_guards/)                             | Guards, security guard mapping, role checks, @Security decorator  |
+| [07_interceptors](https://github.com/xseman/bun-openapi/tree/master/examples/07_interceptors/)                 | Response transformation and short-circuiting                      |
+| [08_logging](https://github.com/xseman/bun-openapi/tree/master/examples/08_logging/)                           | AsyncLocalStorage request context and caller tags                 |
+| [09_complex](https://github.com/xseman/bun-openapi/tree/master/examples/09_complex/)                           | Multi-module composition                                          |
+| [10_mvc](https://github.com/xseman/bun-openapi/tree/master/examples/10_mvc/)                                   | Server-side rendering with @Render and Handlebars                 |
+| [11_jwt-auth](https://github.com/xseman/bun-openapi/tree/master/examples/11_jwt-auth/)                         | JWT Bearer API auth with TypeORM, Bun.password, and jose          |
+| [12_form-auth](https://github.com/xseman/bun-openapi/tree/master/examples/12_form-auth/)                       | Form-based web auth with JWT-in-cookie and Handlebars views       |
+| [13_typeorm-relations](https://github.com/xseman/bun-openapi/tree/master/examples/13_typeorm-relations/)       | TypeORM one-to-many / many-to-one relations                       |
+| [14_session-auth](https://github.com/xseman/bun-openapi/tree/master/examples/14_session-auth/)                 | Stateful server-side sessions with HttpOnly cookie and Handlebars |
 
 ## How To Run An Example
 
 ```sh
-cd examples/basic
+cd examples/01_hello-world
 bun server.ts
 ```

docs/getting-started.md

@@ -149,4 +149,4 @@ Now that you have a running API, explore deeper topics:
 
 ## Runnable Example
 
-See [examples/basic/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/basic/server.ts) for a complete working setup.
+See [examples/02_crud/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/02_crud/server.ts) for a complete working setup.

docs/guides/controllers-and-routes.md

@@ -83,5 +83,5 @@ const app = createApp({
 ## 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)
+- [examples/02_crud/controller.ts](https://github.com/xseman/bun-openapi/blob/master/examples/02_crud/controller.ts)
+- [examples/03_multi-controller/controllers.ts](https://github.com/xseman/bun-openapi/blob/master/examples/03_multi-controller/controllers.ts)

docs/guides/dependency-injection.md

@@ -39,6 +39,6 @@ Use request scope for providers that must be recreated per request.
 
 ## Example
 
-See [examples/dependency-injection/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/dependency-injection/server.ts).
+See [examples/04_dependency-injection/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/04_dependency-injection/server.ts).
 That example can also enable `moduleViewer: true`; because it uses direct
 app-level providers instead of `imports`, the viewer renders an `App` root.

docs/guides/descriptions-and-metadata.md

@@ -152,4 +152,4 @@ This produces a rich Swagger UI entry with clear descriptions, typed response sc
 
 - [Decorator Reference](../reference/decorators.md) — full list of all decorators.
 - [OpenAPI and Swagger](openapi-and-swagger.md) — configuring the spec and Swagger UI.
-- [examples/multi-controller](https://github.com/xseman/bun-openapi/blob/master/examples/multi-controller/) — example using metadata decorators.
+- [examples/03_multi-controller](https://github.com/xseman/bun-openapi/blob/master/examples/03_multi-controller/) — example using metadata decorators.

docs/guides/error-handling.md

@@ -114,4 +114,4 @@ See [Descriptions and Metadata](descriptions-and-metadata.md) for more details o
 
 ## Example
 
-See [examples/basic/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/basic/server.ts).
+See [examples/02_crud/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/02_crud/server.ts).

docs/guides/guards-and-security.md

@@ -57,4 +57,4 @@ const app = createApp({
 
 ## Example
 
-See [examples/guards/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/guards/server.ts) and [examples/security/controller.ts](https://github.com/xseman/bun-openapi/blob/master/examples/security/controller.ts).
+See [examples/06_guards/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/06_guards/server.ts) and [examples/06_guards/controllers.ts](https://github.com/xseman/bun-openapi/blob/master/examples/06_guards/controllers.ts).

docs/guides/interceptors.md

@@ -38,4 +38,4 @@ If validateResponse is enabled, transformed output still needs to match the decl
 
 ## Example
 
-See [examples/interceptors/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/interceptors/server.ts).
+See [examples/07_interceptors/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/07_interceptors/server.ts).

docs/guides/logging-and-caller-context.md

@@ -27,4 +27,4 @@ This lets loggers emit labels like ItemController.create without manual string c
 
 ## Example
 
-See [examples/logging/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/logging/server.ts), [examples/logging/logger.ts](https://github.com/xseman/bun-openapi/blob/master/examples/logging/logger.ts), and [examples/logging/request-context.ts](https://github.com/xseman/bun-openapi/blob/master/examples/logging/request-context.ts).
+See [examples/08_logging/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/08_logging/server.ts), [examples/08_logging/logger.ts](https://github.com/xseman/bun-openapi/blob/master/examples/08_logging/logger.ts), and [examples/08_logging/request-context.ts](https://github.com/xseman/bun-openapi/blob/master/examples/08_logging/request-context.ts).

docs/guides/middleware.md

@@ -32,4 +32,4 @@ Middleware wraps the route before guards, interceptors, and controller execution
 
 ## Example
 
-See [examples/logging/request-context.ts](https://github.com/xseman/bun-openapi/blob/master/examples/logging/request-context.ts) and [examples/logging/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/logging/server.ts).
+See [examples/08_logging/request-context.ts](https://github.com/xseman/bun-openapi/blob/master/examples/08_logging/request-context.ts) and [examples/08_logging/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/08_logging/server.ts).

docs/guides/modules.md

@@ -45,4 +45,4 @@ nodes under an `App` root.
 
 ## Example
 
-See [examples/modules/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/modules/server.ts) and [examples/complex/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/complex/server.ts).
+See [examples/05_modules/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/05_modules/server.ts) and [examples/09_complex/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/09_complex/server.ts).

docs/guides/openapi-and-swagger.md

@@ -59,4 +59,4 @@ const spec = buildSpec([UserController], classValidator(), {
 
 ## Example
 
-See [examples/basic/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/basic/server.ts).
+See [examples/02_crud/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/02_crud/server.ts).

docs/guides/request-binding.md

@@ -78,4 +78,4 @@ whoAmI(@Request() request: Request) {
 
 ## Example
 
-See [examples/basic/controller.ts](https://github.com/xseman/bun-openapi/blob/master/examples/basic/controller.ts).
+See [examples/02_crud/controller.ts](https://github.com/xseman/bun-openapi/blob/master/examples/02_crud/controller.ts).

docs/guides/response-validation.md

@@ -37,4 +37,4 @@ Validation mismatch is treated as a server error and flows through errorFormatte
 
 ## Example
 
-See [examples/interceptors/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/interceptors/server.ts).
+See [examples/07_interceptors/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/07_interceptors/server.ts).

docs/guides/validation-and-schemas.md

@@ -83,5 +83,4 @@ All adapters produce the same result: runtime validation + OpenAPI JSON Schema o
 
 ## Example Projects
 
-- [examples/basic/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/basic/server.ts)
-- [examples/class-validator/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/class-validator/server.ts)
+- [examples/02_crud/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/02_crud/server.ts)

docs/guides/view-rendering.md

@@ -38,4 +38,4 @@ home() {
 
 ## Example
 
-See [examples/mvc/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/mvc/server.ts).
+See [examples/10_mvc/server.ts](https://github.com/xseman/bun-openapi/blob/master/examples/10_mvc/server.ts).

examples/01_hello-world/controller.ts

@@ -0,0 +1,17 @@
+import {
+	Controller,
+	Get,
+	Route,
+	Summary,
+} from "../../src/index.js";
+
+@Route("/")
+class HelloController extends Controller {
+	@Get()
+	@Summary("Say hello")
+	hello() {
+		return { message: "Hello from bun-openapi!" };
+	}
+}
+
+export { HelloController };

examples/interceptors/package.json → examples/01_hello-world/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "bun-openapi-example-interceptors",
+	"name": "bun-openapi-example-01-hello-world",
 	"type": "module",
 	"private": true,
 	"scripts": {

examples/class-validator/server.ts → examples/01_hello-world/server.ts

@@ -1,18 +1,18 @@
 import { classValidator } from "../../src/adapters/class-validator.js";
 import { createApp } from "../../src/index.js";
-import { UserController } from "./controller.js";
+import { HelloController } from "./controller.js";
 
 const port = 3_000;
 
 const app = createApp({
 	schema: classValidator(),
-	controllers: [UserController],
 	swagger: true,
+	controllers: [HelloController],
 	openapi: {
 		service: {
-			name: "class-validator-example",
+			name: "hello-world",
 			version: "1.0.0",
-			description: "CRUD example using class-validator DTO classes with bun-openapi",
+			description: "Minimal bun-openapi app: a single GET endpoint with automatic Swagger UI. No DTOs, no validation.",
 		},
 	},
 });
@@ -25,15 +25,8 @@ Bun.serve({
 	fetch: app.fetch,
 });
 
-console.table(
-	Object.entries(app.routes).map(([path, handlers]) => ({
-		path: path,
-		methods: Object.keys(handlers).join(", "),
-	})),
-);
-
 console.table([
 	{ name: "Server", url: `http://localhost:${port}` },
-	{ name: "Docs Index", url: `http://localhost:${port}/docs/` },
+	{ name: "GET /", url: `http://localhost:${port}/` },
 	{ name: "Swagger UI", url: `http://localhost:${port}/docs/swagger/` },
 ]);

examples/basic/controller.ts → examples/02_crud/controller.ts

@@ -28,7 +28,7 @@ const users = new Map<string, { id: string; name: string; email: string; created
 
 @Route("/users")
 @Tags("Users")
-class UserController extends Controller {
+export class UserController extends Controller {
 	@Get()
 	@Summary("List users")
 	@Description("Returns a paginated list of users, optionally filtered by search term")
@@ -107,10 +107,8 @@ class UserController extends Controller {
 		if (!users.has(params.id)) {
 			throw new NotFoundException("User not found");
 		}
+
 		users.delete(params.id);
 		this.setStatus(204);
-		return undefined;
 	}
 }
-
-export { UserController };

examples/logging/package.json → examples/02_crud/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "bun-openapi-example-logging",
+	"name": "bun-openapi-example-02-crud",
 	"type": "module",
 	"private": true,
 	"scripts": {

examples/basic/server.ts → examples/02_crud/server.ts

@@ -17,9 +17,9 @@ const app = createApp({
 	}),
 	openapi: {
 		service: {
-			name: "basic-example",
+			name: "crud",
 			version: "1.0.0",
-			description: "A basic CRUD API example using class-validator DTOs, HTTP exceptions, and a global error formatter",
+			description: "Full CRUD API with class-validator DTOs, HTTP exceptions, pagination, search, and a global error formatter. Builds on hello-world.",
 		},
 	},
 });

examples/logging/tsconfig.json → examples/02_crud/tsconfig.json

@@ -1,3 +1,3 @@
 {
 	"extends": "../tsconfig.json"
-}
+}

examples/03_multi-controller/package.json

@@ -0,0 +1,11 @@
+{
+	"name": "bun-openapi-example-03-multi-controller",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"start": "bun run server.ts"
+	},
+	"dependencies": {
+		"class-validator": "*"
+	}
+}

examples/multi-controller/server.ts → examples/03_multi-controller/server.ts

@@ -14,9 +14,9 @@ const app = createApp({
 	swagger: true,
 	openapi: {
 		service: {
-			name: "multi-controller-example",
+			name: "multi-controller",
 			version: "1.0.0",
-			description: "Example with multiple controllers, operation IDs, deprecated endpoints, hidden routes, and CSV responses",
+			description: "Multiple controllers, @OperationId, @Deprecated, @Hidden, and @Produces for CSV responses. Builds on crud.",
 		},
 	},
 });