Binder

openapi_first.binder

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.

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.