updated docs strings and added README.md

openapi_first/binder.py

@@ -1,33 +1,35 @@
 """
+# Summary
+
 OpenAPI-driven route binding for FastAPI.
 
----
-
-## Summary
-
 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.
+between OpenAPI operations and Python handler functions using `operationId`.
 
 Notes:
     **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
+        - 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
+        - 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.
 
     **Constraints:**
 
-        - This module intentionally does NOT: Perform request or response validation, generate Pydantic models, modify FastAPI dependency injection, or interpret OpenAPI semantics beyond routing metadata.
+        - This module intentionally does NOT:
+            - Perform request or response validation.
+            - Generate Pydantic models.
+            - Modify FastAPI dependency injection.
+            - Interpret OpenAPI semantics beyond routing metadata.
 """
 
 from fastapi.routing import APIRoute
@@ -45,21 +47,26 @@ def bind_routes(app, spec: dict, routes_module) -> None:
         spec (dict):
             Parsed OpenAPI 3.x specification dictionary.
         routes_module (module):
-            Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.
+            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.
+            If an `operationId` is missing from the spec or if no corresponding
+            handler function exists in the routes module.
 
     Notes:
         **Responsibilities:**
 
-            - Iterates through the OpenAPI specification paths and methods
-            - Resolves each operationId to a handler function, and registers a corresponding APIRoute on the FastAPI application
+            - Iterates through the OpenAPI specification paths and methods.
+            - Resolves each `operationId` to a handler function, and registers
+              a corresponding `APIRoute` on the FastAPI application.
 
         **Guarantees:**
 
-            - Route registration is deterministic and spec-driven. No route decorators are required or supported. Handler resolution errors surface at application startup.
+            - Route registration is deterministic and spec-driven. No route
+              decorators are required or supported. Handler resolution errors
+              surface at application startup.
     """
 
     paths = spec.get("paths", {})