Binder

openapi_first.binder

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.

Classes

Functions

bind_routes

bind_routes(
    app: FastAPI,
    spec: dict[str, Any],
    routes_module: ModuleType,
    security_deps: dict[str, list[Any]] | None = None,
) -> None

Bind OpenAPI operations to FastAPI routes.

Parameters:

Name	Type	Description	Default
app	FastAPI	The FastAPI application instance to which routes will be added.	required
spec	dict[str, Any]	Parsed OpenAPI 3.x specification dictionary.	required
routes_module	ModuleType	Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.	required
security_deps	dict[str, list[Any]] | None	Optional mapping of METHOD:/path → list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.	None

Raises:

Type	Description
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.
- Injects FastAPI ``Depends()`` for each security requirement found
  on the operation or inherited from the top-level ``security`` field.

Guarantees:

- Route registration is deterministic and spec-driven. No route
  decorators are required or supported. Handler resolution errors
  surface at application startup.