Phase 2.2–2.5 docs + Phase 3 feature parity (openapi_extra, Enum coercion, CLI)

[EshwarCVS]

Summary

This PR completes Phase 2.2–2.5 (docs expansion + site UX) and Phase 3 (feature parity + CLI) from the project roadmap.

---

Phase 2.2 — Advanced User Guide

• docs/advanced/additional-responses.md (new) — Documents the responses= parameter: multiple status codes with schemas, shared error models (COMMON_ERRORS dict pattern), response headers, multiple content types, and the "default" catch-all key.

Phase 2.3 — Deployment Guides

• docs/deployment/systemd.md (new) — Full systemd unit file with security hardening (PrivateTmp, ProtectSystem, NoNewPrivileges), EnvironmentFile for secrets, socket activation, journald log commands, zero-downtime SIGHUP reload.
• docs/deployment/gunicorn.md (new) — Gunicorn + UvicornWorker setup, gunicorn.conf.py with max_requests jitter and preload_app caveats, worker sizing formula, Docker and systemd integration.
• docs/deployment/https.md (new) — Let's Encrypt + Certbot walkthrough, hardened Nginx TLS config (TLS 1.2/1.3, HSTS, security headers), auto-renewal deploy hook, TLS verification commands.

Phase 2.4 — Conceptual Docs

• docs/concepts/msgspec-vs-pydantic.md (new) — Philosophy table, performance benchmark table (~5× across encode/decode/construction), full API side-by-side comparisons (decode, encode, field opts, validators), coercion and mutability differences, migration table, step-by-step migration guide.
• docs/concepts/radix-tree-routing.md (new) — O(k) complexity proof vs linear/regex routers, visual tree diagram, annotated iterative _walk algorithm, __slots__ rationale, static-before-param priority, routing benchmark table, documented limitations (no regex constraints, no catch-all).

Phase 2.5 — Docs Site UX (mkdocs.yml)

• Prev/next navigation: navigation.footer feature
• Edit-on-GitHub + View source: content.action.edit / content.action.view
• OpenGraph + Twitter card meta tags: docs/overrides/main.html injects og:* and twitter:* on every page via custom_dir
• mike versioning: mike plugin + extra.version.provider: mike for navbar version selector
• Search enhancements: search.highlight, search.suggest, search.share
• Code annotations: content.code.annotate
• New markdown extensions: pymdownx.snippets, pymdownx.emoji, footnotes
• mike>=2.0.0 added to docs optional deps

---

Phase 3.2 — Core Feature Gaps

openapi_extra= on route decorators (app.py, router.py, openapi/generator.py)

• All route decorators now accept openapi_extra: dict | None
• The OpenAPI generator merges it into the operation object; the responses key is deep-merged so the primary 200 response is preserved alongside any extra ones
• Works on both Faster app decorators and FasterRouter decorators

@app.get("/items", openapi_extra={"x-internal": True, "externalDocs": {"url": "..."}})
async def list_items(): ...

Enum path parameter coercion (dependencies.py)

• New _coerce_path_value() helper called from both explicit Path markers and the implicit fallback
• String-valued enums: passes raw string to annotation() directly
• Numeric enums (IntEnum): coerces string → value type first, so "2" → Priority(2)
• Invalid values return 422 with a clear "permitted: [...]" message

class Color(enum.Enum):
    RED = "red"

@app.get("/colors/{color}")
async def get_color(color: Color):   # "red" → Color.RED automatically
    return {"value": color.value}

Phase 3.3 — CLI Tool (FasterAPI/cli.py + pyproject.toml)

New fasterapi entrypoint with four sub-commands:

Command	Description
fasterapi run [app]	Wraps uvicorn, production mode; workers default to 2×cores+1
fasterapi dev [app]	Same with --reload; no workers flag
fasterapi new <name>	Scaffolds a complete project (lifespan, CRUD router, pyproject, Dockerfile, .gitignore)
fasterapi migrate-from-fastapi <path> [--dry-run]	Rewrites fastapi imports to FasterAPI across a file/directory tree

---

Test plan

• tests/test_phase3.py — 29 new tests covering openapi_extra (5 cases), Enum coercion (6 cases including IntEnum numeric coercion), and all CLI commands (18 cases including scaffold file creation, migration rewriting, dry-run, edge cases)
• Full suite: 291/291 tests pass on rebased branch
• Branch rebased cleanly onto current master (no stale benchmark-sync commits)

[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: improvement detected.

HTTP throughput (FasterAPI vs FastAPI vs Fiber)

Endpoint	FasterAPI	FastAPI	Fiber (Go)	F / Fast
GET /health	472/s	471/s	476/s	1.00x
GET /users/{id}	493/s	487/s	500/s	1.01x
POST /users	439/s	450/s	446/s	0.98x

Direct ASGI (no HTTP; 50,000 iterations)

Endpoint	FasterAPI	FastAPI	Speedup	vs README ASGI ratio
GET /health	193,310/s	19,546/s	9.89x	+44.4%
GET /users/{id}	160,591/s	13,376/s	12.01x	+37.5%
POST /users	102,583/s	10,705/s	9.58x	+34.0%

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

Router	Ops/s	Speedup	vs README
Radix	946,751	10.1x	+32.6%
Regex	93,963	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.