docs: comprehensive documentation covering all gap-analysis items

[EshwarCVS]

Summary

Fills every documentation gap identified in the gap analysis against FastAPI's docs.

45 new pages added across 8 new sections:

• Tutorial series (12 pages) — path/query params, request body, response model, form & file uploads, error handling, dependencies, background tasks, middleware, WebSockets, metadata & docs
• Advanced User Guide (14 pages) — custom responses, cookies/headers, direct Request access, settings/env vars, OpenAPI customisation, Jinja2 templates, lifespan events, behind-proxy, sub-applications, SSE, testing overrides, async tests, bigger apps
• Security (4 pages) — OAuth2 + JWT, OAuth2 scopes, HTTP Basic Auth intro
• Database Integration (4 pages) — SQLAlchemy async, MongoDB/Motor, async patterns
• Deployment (5 pages) — Docker (multi-stage), Nginx/Traefik, AWS/GCP/Azure, Kubernetes
• Concepts (3 pages) — async/await primer, concurrency & parallelism, Python type hints
• How-To Recipes — 15 practical patterns
• FAQ & Troubleshooting — installation, runtime, validation, middleware, WebSocket issues
• Changelog page (visible in docs nav)

5 existing pages enhanced:

• getting-started.md — curl examples, full import table, project layout
• benchmarks.md — environment spec, methodology, result interpretation
• migration-from-fastapi.md — gotcha list, msgspec field equivalents, real-world case studies
• api-reference.md — full prose docs for every exported symbol with usage examples
• mkdocs.yml — navigation tabs, all new pages, extra markdown extensions

Test plan

• mkdocs build succeeds with no warnings
• All nav links resolve (no 404s)
• Code examples are syntactically correct Python
• Docs deploy via existing docs.yml workflow

[github-actions]

Benchmark results

Ubuntu runner, Python 3.13. HTTP table uses the same httpx load against uvicorn (Python) and Fiber (Go). Direct ASGI (below) is Python-only and excludes network I/O.

🔴 Benchmark status: regression detected (>= 5% slower). Do not merge this PR until fixed.

Regression details

• ASGI POST /users speedup: -13.7% vs README baseline

HTTP throughput (FasterAPI vs FastAPI vs Fiber)

Endpoint	FasterAPI	FastAPI	Fiber (Go)	F / Fast
GET /health	536/s	550/s	555/s	0.97x
GET /users/{id}	597/s	603/s	598/s	0.99x
POST /users	517/s	527/s	509/s	0.98x

Direct ASGI (no HTTP; 50,000 iterations)

Endpoint	FasterAPI	FastAPI	Speedup	vs README ASGI ratio
GET /health	202,659/s	28,958/s	7.00x	+2.2%
GET /users/{id}	182,841/s	20,756/s	8.81x	0.9%
POST /users	109,722/s	17,785/s	6.17x	-13.7%

Routing (radix vs regex, 1,500,000 lookups)

Router	Ops/s	Speedup	vs README
Radix	933,557	9.0x	+18.8%
Regex	103,430	1.0x

How to read this

• F / Fast = FasterAPI req/s ÷ FastAPI req/s on the same HTTP harness (higher is better).
• Fiber uses the Go app in benchmarks/fiber (same routes). Go is often several times faster than Python here; the important guard for regressions is check_regressions.py (ASGI + routing floors), which must pass in this workflow.
• vs README compares combined speedups to documented reference numbers (local machine); CI absolute req/s differs by hardware.