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: Any) -> 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	Parsed OpenAPI 3.x specification dictionary.	required
routes_module	module	Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.	required

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.

Guarantees:

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