fixing examples and adding doc strings

openapi_first/app.py

@@ -84,14 +84,16 @@ class OpenAPIFirstApp(FastAPI):
 
     Example
     -------
-    >>> from openapi_first import OpenAPIFirstApp
-    >>> import app.routes as routes
-    >>>
-    >>> app = OpenAPIFirstApp(
-    ...     openapi_path="app/openapi.json",
-    ...     routes_module=routes,
-    ...     title="Example Service"
-    ... )
+    ```python
+    from openapi_first import OpenAPIFirstApp
+    import app.routes as routes
+
+    app = OpenAPIFirstApp(
+        openapi_path="app/openapi.json",
+        routes_module=routes,
+        title="Example Service",
+    )
+    ```
     """
 
     def __init__(

openapi_first/client.py

@@ -1,3 +1,61 @@
+"""
+openapi_first.client
+====================
+
+OpenAPI-first HTTP client for contract-driven services.
+
+This module provides `OpenAPIClient`, a thin, strict HTTP client that
+derives all callable operations directly from an OpenAPI 3.x specification.
+
+It is the client counterpart to `OpenAPIFirstApp`.
+
+Core principles
+---------------
+- The OpenAPI specification is the single source of truth.
+- Each operationId becomes a callable Python method.
+- No implicit schema mutation or inference.
+- No code generation step.
+- Minimal abstraction over httpx.
+
+What this module does
+---------------------
+- Parses an OpenAPI 3.x specification.
+- Dynamically creates one callable per operationId.
+- Enforces presence of:
+  - servers
+  - paths
+  - operationId
+- Formats path parameters safely.
+- Handles JSON request bodies explicitly.
+- Returns raw `httpx.Response` objects.
+
+What this module does NOT do
+----------------------------
+- It does not generate client code.
+- It does not validate request/response schemas.
+- It does not deserialize responses.
+- It does not retry requests.
+- It does not implement authentication helpers.
+- It does not assume non-2xx responses are failures.
+
+Intended usage
+--------------
+This client is designed for:
+
+- Service-to-service communication
+- Integration testing
+- Contract-driven internal SDK usage
+- Systems that want OpenAPI-first symmetry with `OpenAPIFirstApp`
+
+Design constraints
+------------------
+- Only the first server in the OpenAPI `servers` list is used if
+  `base_url` is not explicitly provided.
+- Only explicitly declared request bodies are allowed.
+- `application/json` is handled natively; other media types are sent as raw content.
+- All responses are returned as-is.
+"""
+
 from typing import Any, Callable, Dict, Optional
 from urllib.parse import urljoin
 
@@ -14,9 +72,66 @@ class OpenAPIClient:
     """
     OpenAPI-first HTTP client (httpx-based).
 
+    This client derives all callable methods directly from an OpenAPI 3.x
+    specification. Each operationId becomes a method on the client
+    instance.
+
+    Design principles
+    -----------------
     - One callable per operationId
     - Explicit parameters (path, query, headers, body)
     - No implicit schema inference or mutation
+    - Returns raw httpx.Response objects
+    - No response validation or deserialization
+
+    Parameters
+    ----------
+    spec : dict
+        Parsed OpenAPI 3.x specification.
+    base_url : str | None
+        Base URL of the target service. If omitted, the first entry
+        in the OpenAPI `servers` list is used.
+    client : httpx.Client | None
+        Optional preconfigured httpx client instance.
+
+    Raises
+    ------
+    OpenAPIClientError
+        If:
+        - No servers are defined and base_url is not provided
+        - OpenAPI spec has no paths
+        - An operation is missing operationId
+        - Duplicate operationIds are detected
+        - Required path parameters are missing
+        - Required request body is missing
+
+     Example
+    -------
+    ```python
+    from openapi_first import loader, client
+
+    spec = loader.load_openapi("openapi.yaml")
+
+    api = client.OpenAPIClient(
+        spec=spec,
+        base_url="http://localhost:8000",
+    )
+
+    # Call operationId: getUser
+    response = api.getUser(
+        path_params={"user_id": 123}
+    )
+
+    print(response.status_code)
+    print(response.json())
+
+    # Call operationId: createUser
+    response = api.createUser(
+        body={"name": "Bob"}
+    )
+
+    print(response.status_code)
+    ```
     """
 
     def __init__(