Derive JSON Schema from Python type hints in OpenAPI output

qh builds every route with a generic endpoint(request: Request) signature,
so the wrapped function's parameters and return type are invisible to
FastAPI's OpenAPI machinery: /openapi.json had empty {} request/response
schemas and no components.schemas, and openapi-typescript produced no
useful types.

This derives a complete OpenAPI document from the wrapped functions' Python
type hints — additive, with the request-handling path untouched:

- qh/openapi.py: python_type_to_json_schema() converts Python type hints to
  JSON Schema (primitives, list/dict/tuple, Optional/Union incl. PEP 604,
  Literal, Any, dataclasses, TypedDicts incl. total=False, Pydantic models,
  NamedTuples, Enums). Named composites are registered in components.schemas
  and referenced by $ref; the recursion guard handles self-referential types.
- enhance_openapi_schema() now fills requestBody, parameters (path/query),
  responses.200 and components.schemas.
- install_enhanced_openapi() overrides app.openapi to serve the enriched doc
  at /openapi.json, with a defensive fallback to FastAPI's plain schema.
- endpoint.py exposes the resolved param -> HTTP-location map; app.py
  surfaces it via inspect_routes — single source of truth for body/path/query
  classification.
- mk_app(enhanced_openapi=True) installs it by default.

Adds qh/tests/test_openapi_schema.py (27 tests).

Closes #8

Author: thorwhalen

qh/__init__.py

@@ -23,7 +23,12 @@
 from qh.types import register_type, register_json_type, TypeRegistry
 
 # OpenAPI and client generation (Phase 3)
-from qh.openapi import export_openapi, enhance_openapi_schema
+from qh.openapi import (
+    export_openapi,
+    enhance_openapi_schema,
+    install_enhanced_openapi,
+    python_type_to_json_schema,
+)
 from qh.client import (
     mk_client_from_openapi,
     mk_client_from_url,
@@ -117,6 +122,8 @@
     # OpenAPI & Client (Phase 3)
     "export_openapi",
     "enhance_openapi_schema",
+    "install_enhanced_openapi",
+    "python_type_to_json_schema",
     "mk_client_from_openapi",
     "mk_client_from_url",
     "mk_client_from_app",

qh/app.py

@@ -32,6 +32,7 @@ def mk_app(
     use_conventions: bool = False,
     async_funcs: Optional[List[Union[str, Callable]]] = None,
     async_config: Optional[Union[Dict[str, Any], "TaskConfig"]] = None,
+    enhanced_openapi: bool = True,
     **kwargs,
 ) -> FastAPI:
     """
@@ -69,6 +70,12 @@ def mk_app(
             - TaskConfig object (applies to all async_funcs)
             - Dict mapping function names to TaskConfig objects
 
+        enhanced_openapi: Whether to serve an enhanced OpenAPI document at
+            ``/openapi.json`` — one with ``requestBody`` / ``responses`` /
+            ``components.schemas`` derived from each function's Python type
+            hints (see :mod:`qh.openapi`). Defaults to True; the enhancement is
+            additive and falls back to FastAPI's plain schema if it ever fails.
+
         **kwargs: Additional FastAPI() constructor kwargs (if creating new app)
 
     Returns:
@@ -254,6 +261,13 @@ def mk_app(
                 if task_config and getattr(task_config, "create_task_endpoints", True):
                     add_task_endpoints(app, func.__name__)
 
+    # Serve an OpenAPI document with full request/response JSON Schema derived
+    # from the wrapped functions' Python type hints.
+    if enhanced_openapi:
+        from qh.openapi import install_enhanced_openapi
+
+        install_enhanced_openapi(app)
+
     return app
 
 
@@ -280,6 +294,10 @@ def inspect_routes(app: FastAPI) -> List[Dict[str, Any]]:
             # Include original function if available (for OpenAPI/client generation)
             if hasattr(route.endpoint, "_qh_original_func"):
                 route_info["function"] = route.endpoint._qh_original_func
+            # Include the resolved param -> TransformSpec map (HTTP-location
+            # classification) for OpenAPI request/response schema generation.
+            if hasattr(route.endpoint, "_qh_param_specs"):
+                route_info["param_specs"] = route.endpoint._qh_param_specs
             routes.append(route_info)
 
     return routes

qh/endpoint.py

@@ -312,6 +312,12 @@ def task_wrapper(**kwargs):
     endpoint.__doc__ = func.__doc__
     # Store original function for OpenAPI/client generation
     endpoint._qh_original_func = func  # type: ignore
+    # Store the resolved param -> TransformSpec map (the single source of truth
+    # for which HTTP location each parameter is read from). OpenAPI generation
+    # (qh.openapi) consumes this to classify body/path/query parameters without
+    # re-deriving the logic.
+    endpoint._qh_param_specs = param_specs  # type: ignore
+    endpoint._qh_route_config = route_config  # type: ignore
 
     return endpoint