**Date:** 2026-04-18

HawkAPI currently **matches or exceeds FastAPI on ~85 % of the tutorial-level DX surface**, and meaningfully exceeds on differentiators FastAPI does not ship at all (API versioning, permission policies, built-in bulkhead/circuit-breaker/rate-limiter, observability, migration codemod, PEP 703 wheels).

The five gaps below are the ones that hurt migration from a real FastAPI codebase the most — not because they are large engineering tasks, but because they are everywhere in FastAPI tutorials and copy-pasted into real production code:

| # | Gap | Severity | Effort |

|---|---|---|---|

| 1 | **Yield-dependencies with per-request finalization** | Critical | M |

| 2 | **Route-level `dependencies=[Depends(...)]`** on decorators | Important | S |

| 3 | **`response_model_exclude_none/unset/defaults`** flags | Important | S |

| 4 | **OAuth2 scopes enforcement + OpenAPI reflection** | Important | M |

| 5 | **`status` module with HTTP_NNN constants** | Minor (cosmetic) | XS |

Everything else is either already present or a known out-of-scope differentiator. The non-gap surplus (built-in versioning, bulkhead, observability, codemod, etc.) is strong; the five items above close the last mile of "FastAPI users land on HawkAPI and nothing is missing."

| Route-level `dependencies=[...]` (side-effect deps) | — | ❌ | Must use app-level hooks or middleware today (**Gap #2**) |

| `yield` dependencies with teardown after response | — | ⚠️ | App-level `lifespan` only; no per-request yield-dep (**Gap #1**) |

| Path-operation-level `dependencies=[...]` | — | ❌ | Requires middleware today (**Gap #2**) |

| Global (app-level) dependencies | — | ❌ | Workaround: middleware |

| `response_model_exclude_none/unset/defaults` | — | ❌ | Not wired (**Gap #3**) |

| `from fastapi import status` → `status.HTTP_201_CREATED` | — | ❌ | No constants module (**Gap #5**) |

**Severity:** Critical **Effort:** M

**What FastAPI has:**

async def get_db() -> AsyncIterator[AsyncSession]:

async with SessionLocal() as session:

yield session # returned to handler

@app.get("/users")

async def list_users(db: AsyncSession = Depends(get_db)) -> list[User]:

...

This is THE pattern in FastAPI tutorials and production code for database sessions, HTTP clients, Redis connections, transactions. Every SQLAlchemy/Databases example depends on it.

**What HawkAPI has:** App-level `lifespan` context manager for long-lived resources. No per-request teardown.

**Work required:**

- Extend `src/hawkapi/di/param_plan.py` to detect generator/async-generator dependencies.

- Register each yield-dep on a per-request stack (push on entry, pop + run remaining code after the handler's response body is sent).

- Ensure cancellation and exception paths run the finalizers.

- Wire teardown to run AFTER response headers+body flushed (like FastAPI) so the client isn't blocked.

- Test: yield that raises during teardown — how should the error be reported? (FastAPI: logs, ignores.)

**Payoff:** Single biggest migration-friction item for any FastAPI user with a database.

**Severity:** Important **Effort:** S

**What FastAPI has:**

@app.get("/admin/reports", dependencies=[Depends(require_admin)])

async def reports() -> ...:

...

Used pervasively for auth guards, audit-log writers, rate-limit increments that don't need a return value. Also accepted on `APIRouter(dependencies=[...])` for whole-router guards.

**What HawkAPI has:** Workaround via app-level hooks or middleware. No decorator-level kwarg.

**Work required:**

- Add `dependencies: Sequence[Depends] | None = None` kwarg to the route decorators in `src/hawkapi/routing/router.py`.

- Add the same kwarg on the `Router` class constructor and `include_router` call; merge router-level + route-level lists.

- On request: resolve each `Depends` before invoking the handler; any raised exception short-circuits (consistent with FastAPI behavior).

- Make the results *not* injected into the handler's signature — they're executed for side effects only.

- Tests: chain ordering, exceptions, interaction with yield-dependencies.

**Payoff:** Biggest ergonomic win for anyone who reads FastAPI auth examples and copy-pastes.

**Severity:** Important **Effort:** S

**What FastAPI has:**

@app.get(

"/items/{id}",

response_model=Item,

response_model_exclude_none=True, # drop keys whose value is None

response_model_exclude_unset=True, # drop keys the user didn't set

response_model_exclude_defaults=True, # drop keys equal to their default

)

Used for:

- APIs where optional fields shouldn't serialize as `"field": null`

- Versioned responses where fields were added later and old clients shouldn't see them

- Admin vs public response shapes

**What HawkAPI has:** `response_model` accepted on routes; the three exclusion knobs are not wired through to the serializer.

**Work required:**

- Plumb three flags from route metadata → `src/hawkapi/serialization/encoder.py`.

- msgspec already supports field exclusion at encode time; map the flags onto its API.

- Tests per flag + combinations.

**Payoff:** Low-effort closure of a feature 70 % of FastAPI response_model users eventually reach for.

**Severity:** Minor (but high frequency) **Effort:** XS

**What FastAPI has:**

from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)

async def create_item(...): ...

Pure cosmetic convenience re-exported from Starlette. Everyone uses it.

**What HawkAPI has:** Users hardcode `201`.

**Work required:**

- Create `src/hawkapi/status.py` re-exporting the standard HTTP constants (can copy from Starlette's `starlette.status`, or use `http.HTTPStatus`'s integer values).

- Export `status` from `hawkapi/__init__.py` so `from hawkapi import status` works.

- One-line unit test.

**Payoff:** Removes a paper cut. A one-hour job that eliminates a reason someone says "HawkAPI is missing things FastAPI has."

Each of the top-5 gaps becomes its own design spec + implementation plan. Recommended order (smallest effort / highest ratio first, to accumulate shipped wins):

1. **Gap #5** (`status` constants) — afternoon of work.

2. **Gap #3** (`response_model_exclude_*`) — one spec, small impl.

3. **Gap #2** (`dependencies=[...]` kwarg) — clean decorator change.

4. **Gap #1** (yield-dependencies) — the big one, touches DI core.

5. **Gap #4** (OAuth2 scopes) — biggest surface area, last.

This order gives four visible DX-parity wins before the fifth (scopes) takes more effort. Each gets an independent cycle — spec → plan → implement — following the workflow used for Tier 1 and Tier 2.