101 lines
3.3 KiB
Python
101 lines
3.3 KiB
Python
"""
|
|
# Summary
|
|
|
|
OpenAPI-driven route binding for FastAPI.
|
|
|
|
This module is responsible for translating an OpenAPI 3.x specification
|
|
into concrete FastAPI routes. It enforces a strict one-to-one mapping
|
|
between OpenAPI operations and Python handler functions using `operationId`.
|
|
|
|
Notes:
|
|
**Core Responsibility:**
|
|
|
|
- Read path + method definitions from an OpenAPI specification.
|
|
- Resolve each `operationId` to a Python callable.
|
|
- Register routes with FastAPI using `APIRoute`.
|
|
- Fail fast when contract violations are detected.
|
|
|
|
**Design Constraints:**
|
|
|
|
- All routes MUST be declared in the OpenAPI specification.
|
|
- All OpenAPI operations MUST define an `operationId`.
|
|
- Every `operationId` MUST resolve to a handler function.
|
|
- Handlers are plain Python callables (no decorators required).
|
|
- No implicit route creation or inference is allowed.
|
|
|
|
**Constraints:**
|
|
|
|
- This module intentionally does NOT:
|
|
- Perform request or response validation.
|
|
- Generate Pydantic models.
|
|
- Modify FastAPI dependency injection.
|
|
- Interpret OpenAPI semantics beyond routing metadata.
|
|
"""
|
|
|
|
from fastapi.routing import APIRoute
|
|
|
|
from .errors import MissingOperationHandler
|
|
|
|
|
|
def bind_routes(app, spec: dict, routes_module) -> None:
|
|
"""
|
|
Bind OpenAPI operations to FastAPI routes.
|
|
|
|
Args:
|
|
app (fastapi.FastAPI):
|
|
The FastAPI application instance to which routes will be added.
|
|
spec (dict):
|
|
Parsed OpenAPI 3.x specification dictionary.
|
|
routes_module (module):
|
|
Python module containing handler functions. Each handler's name MUST
|
|
exactly match an OpenAPI `operationId`.
|
|
|
|
Raises:
|
|
MissingOperationHandler:
|
|
If an `operationId` is missing from the spec or if no corresponding
|
|
handler function exists in the routes module.
|
|
|
|
Notes:
|
|
**Responsibilities:**
|
|
|
|
- Iterates through the OpenAPI specification paths and methods.
|
|
- Resolves each `operationId` to a handler function, and registers
|
|
a corresponding `APIRoute` on the FastAPI application.
|
|
|
|
**Guarantees:**
|
|
|
|
- Route registration is deterministic and spec-driven. No route
|
|
decorators are required or supported. Handler resolution errors
|
|
surface at application startup.
|
|
"""
|
|
|
|
paths = spec.get("paths", {})
|
|
|
|
for path, methods in paths.items():
|
|
for http_method, operation in methods.items():
|
|
|
|
operation_id = operation.get("operationId")
|
|
if not operation_id:
|
|
raise MissingOperationHandler(
|
|
path=path,
|
|
method=http_method,
|
|
)
|
|
|
|
try:
|
|
endpoint = getattr(routes_module, operation_id)
|
|
except AttributeError:
|
|
raise MissingOperationHandler(
|
|
path=path,
|
|
method=http_method,
|
|
operation_id=operation_id,
|
|
)
|
|
|
|
route = APIRoute(
|
|
path=path,
|
|
endpoint=endpoint,
|
|
methods=[http_method.upper()],
|
|
name=operation_id,
|
|
)
|
|
|
|
app.router.routes.append(route)
|