Skip to content

Binder

openapi_first.binder

openapi_first.binder

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.

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.

This module intentionally does NOT:

  • Perform request or response validation
  • Generate Pydantic models
  • Modify FastAPI dependency injection
  • Interpret OpenAPI semantics beyond routing metadata

Those concerns belong to other layers or tooling.

bind_routes 

bind_routes(app: FastAPI, spec: Dict[str, Any], routes_module: Any) -> None

Bind OpenAPI operations to FastAPI routes.

Iterates through the OpenAPI specification paths and methods, resolves each operationId to a handler function, and registers a corresponding APIRoute on the FastAPI application.

Parameters

app : fastapi.FastAPI The FastAPI application instance to which routes will be added.

dict

Parsed OpenAPI 3.x specification dictionary.

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.

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