openapi-first/docs/mcp/modules/openapi_first.binder.json

{
  "module": "openapi_first.binder",
  "content": {
    "path": "openapi_first.binder",
    "docstring": "# Summary\n\nOpenAPI-driven route binding for FastAPI.\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using `operationId`.\n\nNotes:\n    **Core Responsibility:**\n\n        - Read path + method definitions from an OpenAPI specification.\n        - Resolve each `operationId` to a Python callable.\n        - Register routes with FastAPI using `APIRoute`.\n        - Fail fast when contract violations are detected.\n\n    **Design Constraints:**\n\n        - All routes MUST be declared in the OpenAPI specification.\n        - All OpenAPI operations MUST define an `operationId`.\n        - Every `operationId` MUST resolve to a handler function.\n        - Handlers are plain Python callables (no decorators required).\n        - No implicit route creation or inference is allowed.\n\n    **Constraints:**\n\n        - This module intentionally does NOT:\n            - Perform request or response validation.\n            - Generate Pydantic models.\n            - Modify FastAPI dependency injection.\n            - Interpret OpenAPI semantics beyond routing metadata.",
    "objects": {
      "ModuleType": {
        "name": "ModuleType",
        "kind": "alias",
        "path": "openapi_first.binder.ModuleType",
        "signature": "<bound method Alias.signature of Alias('ModuleType', 'types.ModuleType')>",
        "docstring": null
      },
      "Any": {
        "name": "Any",
        "kind": "alias",
        "path": "openapi_first.binder.Any",
        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
        "docstring": null
      },
      "FastAPI": {
        "name": "FastAPI",
        "kind": "alias",
        "path": "openapi_first.binder.FastAPI",
        "signature": "<bound method Alias.signature of Alias('FastAPI', 'fastapi.FastAPI')>",
        "docstring": null
      },
      "APIRoute": {
        "name": "APIRoute",
        "kind": "alias",
        "path": "openapi_first.binder.APIRoute",
        "signature": "<bound method Alias.signature of Alias('APIRoute', 'fastapi.routing.APIRoute')>",
        "docstring": null
      },
      "MissingOperationHandler": {
        "name": "MissingOperationHandler",
        "kind": "class",
        "path": "openapi_first.binder.MissingOperationHandler",
        "signature": "<bound method Alias.signature of Alias('MissingOperationHandler', 'openapi_first.errors.MissingOperationHandler')>",
        "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nNotes:\n    **Scenarios:**\n\n        - An OpenAPI operation does not define an `operationId`.\n        - An `operationId` is defined but no matching function exists in\n          the provided routes module.\n\n    **Guarantees:**\n\n        - This represents a violation of the OpenAPI-first contract and\n          indicates that the specification and implementation are out of\n          sync."
      },
      "bind_routes": {
        "name": "bind_routes",
        "kind": "function",
        "path": "openapi_first.binder.bind_routes",
        "signature": "<bound method Function.signature of Function('bind_routes', 44, 126)>",
        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict[str, Any]):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (ModuleType):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
      }
    }
  }
}