google styled doc

openapi_first/app.py

@@ -1,43 +1,32 @@
 """
-openapi_first.app
-=========================
-
 OpenAPI-first application bootstrap for FastAPI.
 
+---
+
+## Summary
+
 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.
+Notes:
+    **Core Principles:**
 
-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.
+        - 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 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.
+    **Responsibilities:**
 
-Intended usage
---------------
-This module is intended for teams that want:
+        - 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
 
-- OpenAPI-first API development
-- Strong contract enforcement
-- Minimal FastAPI boilerplate
-- Predictable, CI-friendly failures for spec/implementation drift
+    **Constraints:**
+
+        - This module intentionally does NOT: Generate OpenAPI specs, generate client code, introduce a new framework or lifecycle, or alter FastAPI dependency injection semantics.
 """
 
 from fastapi import FastAPI
@@ -50,50 +39,30 @@ 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.
+    Notes:
+        **Responsibilities:**
 
-    Parameters
-    ----------
-    openapi_path : str
-        Filesystem path to the OpenAPI 3.x specification file.
-        This specification is treated as the authoritative API contract.
+            - `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
 
-    routes_module : module
-        Python module containing handler functions whose names correspond
-        exactly to OpenAPI operationId values.
+        **Guarantees:**
 
-    **fastapi_kwargs
-        Additional keyword arguments passed directly to `fastapi.FastAPI`
-        (e.g., title, version, middleware, lifespan handlers).
+            - 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:
+        ```python
+        from openapi_first import OpenAPIFirstApp
+        import app.routes as routes
 
-    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
-    -------
-    ```python
-    from openapi_first import OpenAPIFirstApp
-    import app.routes as routes
-
-    app = OpenAPIFirstApp(
-        openapi_path="app/openapi.json",
-        routes_module=routes,
-        title="Example Service",
-    )
-    ```
+        app = OpenAPIFirstApp(
+            openapi_path="app/openapi.json",
+            routes_module=routes,
+            title="Example Service",
+        )
+        ```
     """
 
     def __init__(
@@ -103,6 +72,21 @@ class OpenAPIFirstApp(FastAPI):
         routes_module,
         **fastapi_kwargs,
     ):
+        """
+        Initialize the application.
+
+        Args:
+            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 (Any):
+                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.
+        """
         # Initialize FastAPI normally
         super().__init__(**fastapi_kwargs)