Skip to content

# 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:

    1
    2
    3
    4

    - 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:

    1
    2
    3
    4
    5

    - 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:

    1
    2
    3
    4
    5

    - 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

    1

    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:

    1
    2
    3

    - 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:

    1
    2
    3

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