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

{
  "module": "openapi_first.app",
  "content": {
    "path": "openapi_first.app",
    "docstring": "# Summary\n\nOpenAPI-first application bootstrap for FastAPI.\n\nThis module provides `OpenAPIFirstApp`, a thin but strict abstraction\nthat enforces OpenAPI as the single source of truth for a FastAPI service.\n\nNotes:\n    **Core Principles:**\n\n        - The OpenAPI specification (JSON or YAML) defines the entire API surface.\n        - Every `operationId` in the OpenAPI spec must have a corresponding\n          Python handler function.\n        - Handlers are plain Python callables (no FastAPI decorators).\n        - FastAPI route registration is derived exclusively from the spec.\n        - FastAPI's autogenerated OpenAPI schema is fully overridden.\n\n    **Responsibilities:**\n\n        - Loads and validates an OpenAPI 3.x specification.\n        - Dynamically binds HTTP routes to handler functions using `operationId`.\n        - Registers routes with FastAPI at application startup.\n        - Ensures runtime behavior matches the OpenAPI contract exactly.\n\n    **Constraints:**\n\n        - This module intentionally does NOT:\n            - Generate OpenAPI specs.\n            - Generate client code.\n            - Introduce a new framework or lifecycle.\n            - Alter FastAPI dependency injection semantics.",
    "objects": {
      "bind_routes": {
        "name": "bind_routes",
        "kind": "function",
        "path": "openapi_first.app.bind_routes",
        "signature": "bind_routes(app: FastAPI, spec: dict[str, Any], routes_module: ModuleType, security_deps: dict[str, list[Any]] | None = None)",
        "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."
      },
      "load_openapi": {
        "name": "load_openapi",
        "kind": "function",
        "path": "openapi_first.app.load_openapi",
        "signature": "load_openapi(path: str | Path)",
        "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nArgs:\n    path (str | Path):\n        Filesystem path to an OpenAPI specification file. Supported\n        extensions: `.json`, `.yaml`, `.yml`.\n\nReturns:\n    dict[str, Any]:\n        Parsed and validated OpenAPI specification.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the file does not exist, cannot be parsed, or fails OpenAPI\n        schema validation.\n\nNotes:\n    **Guarantees:**\n\n        - The specification is parsed based on file extension and validated\n          using a strict OpenAPI schema validator.\n        - Any error results in an immediate exception, preventing\n          application startup."
      },
      "make_security_dependencies": {
        "name": "make_security_dependencies",
        "kind": "function",
        "path": "openapi_first.app.make_security_dependencies",
        "signature": "make_security_dependencies(spec: dict[str, Any], security_schemes: dict[str, dict[str, Any]])",
        "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation."
      },
      "parse_security_schemes": {
        "name": "parse_security_schemes",
        "kind": "function",
        "path": "openapi_first.app.parse_security_schemes",
        "signature": "parse_security_schemes(spec: dict[str, Any])",
        "docstring": "Extract and resolve environment variables in security schemes."
      },
      "OpenAPIFirstApp": {
        "name": "OpenAPIFirstApp",
        "kind": "class",
        "path": "openapi_first.app.OpenAPIFirstApp",
        "signature": "OpenAPIFirstApp(*, openapi_path: str, routes_module: Any, **fastapi_kwargs: Any)",
        "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nArgs:\n    openapi_path (str):\n        Filesystem path to the OpenAPI 3.x specification file. This\n        specification is treated as the authoritative API contract.\n    routes_module (ModuleType):\n        Python module containing handler functions whose names correspond\n        exactly to OpenAPI ``operationId`` values.\n    **fastapi_kwargs (Any):\n        Additional keyword arguments passed directly to\n        ``fastapi.FastAPI`` (e.g., title, version, middleware, lifespan\n        handlers).\n\nRaises:\n    OpenAPIFirstError:\n        If the OpenAPI specification is invalid, or if any declared\n        ``operationId`` does not have a corresponding handler function.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first.app import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
        "members": {
          "openapi": {
            "name": "openapi",
            "kind": "attribute",
            "path": "openapi_first.app.OpenAPIFirstApp.openapi",
            "signature": null,
            "docstring": null
          }
        }
      }
    }
  }
}