updated docs strings and added README.md

openapi_first/__init__.py

@@ -1,71 +1,77 @@
 """
+# Summary
+
 FastAPI OpenAPI First — strict OpenAPI-first application bootstrap for FastAPI.
 
----
-
-## Summary
-
 FastAPI OpenAPI First is a **contract-first infrastructure library** that
 enforces OpenAPI as the single source of truth for FastAPI services.
 
 The library removes decorator-driven routing and replaces it with
 deterministic, spec-driven application assembly. Every HTTP route,
 method, and operation is defined in OpenAPI first and bound to Python
-handlers explicitly via operationId.
+handlers explicitly via `operationId`.
 
 ---
 
-## Installation
+# Installation
 
 Install using pip:
 
-    pip install openapi-first
+```bash
+pip install openapi-first
+```
 
 Or with Poetry:
 
-    poetry add openapi-first
+```bash
+poetry add openapi-first
+```
 
 ---
 
-## Quick start
+# Quick Start
 
 Minimal OpenAPI-first FastAPI application:
 
-    from openapi_first import app
-    import my_service.routes as routes
+```python
+from openapi_first import app
+import my_service.routes as routes
 
-    api = app.OpenAPIFirstApp(
-        openapi_path="openapi.yaml",
-        routes_module=routes,
-        title="My Service",
-        version="1.0.0",
-    )
+api = app.OpenAPIFirstApp(
+    openapi_path="openapi.yaml",
+    routes_module=routes,
+    title="My Service",
+    version="1.0.0",
+)
+```
 
 OperationId-driven HTTP client:
 
-    from openapi_first.loader import load_openapi
-    from openapi_first.client import OpenAPIClient
+```python
+from openapi_first.loader import load_openapi
+from openapi_first.client import OpenAPIClient
 
-    spec = load_openapi("openapi.yaml")
-    client = OpenAPIClient(spec)
+spec = load_openapi("openapi.yaml")
+client = OpenAPIClient(spec)
 
-    response = client.get_health()
+response = client.get_health()
+```
 
 ---
 
-## Architecture
+# Architecture
 
 The library is structured around four core responsibilities:
 
-- **loader**: Load and validate OpenAPI 3.x specifications (JSON/YAML)
-- **binder**: Bind OpenAPI operations to FastAPI routes via operationId
-- **app**: OpenAPI-first FastAPI application bootstrap
-- **client**: OpenAPI-first HTTP client driven by the same specification
-- **errors**: Explicit error hierarchy for contract violations
+- `loader`: Load and validate OpenAPI 3.x specifications (JSON/YAML).
+- `binder`: Bind OpenAPI operations to FastAPI routes via `operationId`.
+- `app`: OpenAPI-first FastAPI application bootstrap.
+- `client`: OpenAPI-first HTTP client driven by the same specification.
+- `errors`: Explicit error hierarchy for contract violations.
 
 ---
 
-## Public API
+# Public API
 
 The supported public API consists of the following top-level modules:
 
@@ -77,14 +83,14 @@ The supported public API consists of the following top-level modules:
 
 ---
 
-## Design Guarantees
+# Design Guarantees
 
-- OpenAPI is the single source of truth
-- No undocumented routes can exist
-- No OpenAPI operation can exist without a handler or client callable
-- All contract violations fail at application startup or client creation
-- No hidden FastAPI magic or implicit behavior
-- Deterministic, testable application assembly
+- OpenAPI is the single source of truth.
+- No undocumented routes can exist.
+- No OpenAPI operation can exist without a handler or client callable.
+- All contract violations fail at application startup or client creation.
+- No hidden FastAPI magic or implicit behavior.
+- Deterministic, testable application assembly.
 
 ---
 """