94 lines
3.1 KiB
Python
94 lines
3.1 KiB
Python
"""
|
|
OpenAPI-driven route binding for FastAPI.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
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, or 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)
|