init openapi_first

2026-01-10 17:21:21 +05:30
parent 76e2599903
commit b88ecbd7c5
5 changed files with 542 additions and 0 deletions
--- a/openapi_first/app.py
+++ b/openapi_first/app.py
@@ -0,0 +1,118 @@
+"""
+fastapi_openapi_first.app
+=========================
+
+OpenAPI-first application bootstrap for FastAPI.
+
+This module provides `OpenAPIFirstApp`, a thin but strict abstraction
+that enforces OpenAPI as the single source of truth for a FastAPI service.
+
+Core principles
+---------------
+- The OpenAPI specification (JSON or YAML) defines the entire API surface.
+- Every operationId in the OpenAPI spec must have a corresponding
+  Python handler function.
+- Handlers are plain Python callables (no FastAPI decorators).
+- FastAPI route registration is derived exclusively from the spec.
+- FastAPI's autogenerated OpenAPI schema is fully overridden.
+
+What this module does
+---------------------
+- Loads and validates an OpenAPI 3.x specification.
+- Dynamically binds HTTP routes to handler functions using operationId.
+- Registers routes with FastAPI at application startup.
+- Ensures runtime behavior matches the OpenAPI contract exactly.
+
+What this module does NOT do
+----------------------------
+- It does not generate OpenAPI specs.
+- It does not generate client code.
+- It does not introduce a new framework or lifecycle.
+- It does not alter FastAPI dependency injection semantics.
+
+Intended usage
+--------------
+This module is intended for teams that want:
+
+- OpenAPI-first API development
+- Strong contract enforcement
+- Minimal FastAPI boilerplate
+- Predictable, CI-friendly failures for spec/implementation drift
+"""
+
+from fastapi import FastAPI
+
+from .loader import load_openapi
+from .binder import bind_routes
+
+
+class OpenAPIFirstApp(FastAPI):
+    """
+    FastAPI application enforcing OpenAPI-first design.
+
+    `OpenAPIFirstApp` subclasses FastAPI and replaces manual route
+    registration with OpenAPI-driven binding. All routes are derived
+    from the provided OpenAPI specification, and each operationId is
+    mapped to a Python function in the supplied routes module.
+
+    Parameters
+    ----------
+    openapi_path : str
+        Filesystem path to the OpenAPI 3.x specification file.
+        This specification is treated as the authoritative API contract.
+
+    routes_module : module
+        Python module containing handler functions whose names correspond
+        exactly to OpenAPI operationId values.
+
+    **fastapi_kwargs
+        Additional keyword arguments passed directly to `fastapi.FastAPI`
+        (e.g., title, version, middleware, lifespan handlers).
+
+    Raises
+    ------
+    OpenAPIFirstError
+        If the OpenAPI specification is invalid, or if any declared
+        operationId does not have a corresponding handler function.
+
+    Behavior guarantees
+    -------------------
+    - No route can exist without an OpenAPI declaration.
+    - No OpenAPI operation can exist without a handler.
+    - Swagger UI and `/openapi.json` always reflect the provided spec.
+    - Handler functions remain framework-agnostic and testable.
+
+    Example
+    -------
+    >>> from fastapi_openapi_first import OpenAPIFirstApp
+    >>> import app.routes as routes
+    >>>
+    >>> app = OpenAPIFirstApp(
+    ...     openapi_path="app/openapi.json",
+    ...     routes_module=routes,
+    ...     title="Example Service"
+    ... )
+    """
+
+    def __init__(
+        self,
+        *,
+        openapi_path: str,
+        routes_module,
+        **fastapi_kwargs,
+    ):
+        # Initialize FastAPI normally
+        super().__init__(**fastapi_kwargs)
+
+        # Load and validate OpenAPI specification
+        self._openapi_spec = load_openapi(openapi_path)
+
+        # Bind routes strictly from OpenAPI spec
+        bind_routes(
+            app=self,
+            spec=self._openapi_spec,
+            routes_module=routes_module,
+        )
+
+        # Override FastAPI's OpenAPI generation
+        self.openapi = lambda: self._openapi_spec