{
  "module": "openapi_first.codegen_routes",
  "content": {
    "path": "openapi_first.codegen_routes",
    "docstring": "# Summary\n\nRoute handler code generation from OpenAPI specifications.\n\nThis module generates Python route handler stubs from an OpenAPI 3.x\nspecification. Each resource (derived from the first path segment)\ngets its own file under the output directory. Every OpenAPI operation\nmust define an ``operationId``, which becomes the handler function name.\n\nNotes:\n    **Design constraints:**\n\n        - ``operationId`` is required on every operation (matching\n          ``binder.bind_routes``).\n        - Handlers are stubs raising ``NotImplementedError``.\n        - Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n          parent resource (``pets``).\n        - Parameter types and defaults are inferred from the spec.\n        - ``response: Response`` is injected for non-200 success codes.\n        - Resource names are sanitized to valid Python module identifiers,\n          so a path such as ``/fetch-requests`` yields ``fetch_requests.py``.\n        - Passing ``inject_request=True`` prepends ``request: Request`` to\n          every handler (the composition-root / DI convention).\n        - ``multipart/form-data`` and\n          ``application/x-www-form-urlencoded`` request bodies expand to one\n          parameter per schema property (``UploadFile`` / ``File`` / ``Form``)\n          instead of an opaque ``payload: dict``.\n        - Passing ``package=True`` writes ``<resource>/routes.py`` (with\n          ``__init__.py`` sidecars) instead of a flat ``<resource>.py``.\n        - Passing ``template_style=True`` emits ``async def`` handlers whose\n          JSON body parameter is named ``body`` (matching the standards\n          template) and adds a service-resolution hint comment.",
    "objects": {
      "load_openapi": {
        "name": "load_openapi",
        "kind": "function",
        "path": "openapi_first.codegen_routes.load_openapi",
        "signature": "load_openapi(path: str | Path)",
        "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nArgs:\n    path (str | Path):\n        Filesystem path to an OpenAPI specification file. Supported\n        extensions: `.json`, `.yaml`, `.yml`.\n\nReturns:\n    dict[str, Any]:\n        Parsed and validated OpenAPI specification.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the file does not exist, cannot be parsed, or fails OpenAPI\n        schema validation.\n\nNotes:\n    **Guarantees:**\n\n        - The specification is parsed based on file extension and validated\n          using a strict OpenAPI schema validator.\n        - Any error results in an immediate exception, preventing\n          application startup."
      },
      "generate_routes": {
        "name": "generate_routes",
        "kind": "function",
        "path": "openapi_first.codegen_routes.generate_routes",
        "signature": "generate_routes(spec_path: Path, output_dir: Path, *, use_models: bool = False, models_module: str = 'models', inject_request: bool = False, package: bool = False, template_style: bool = False) -> list[Path]",
        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one route module per resource in *output_dir*. Resources are\nderived from the first path segment (e.g. ``/pets`` and ``/pets/{id}``\nboth group under ``pets``) and sanitized to valid module identifiers.\n\nArgs:\n    spec_path (Path):\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir (Path):\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models (bool, optional):\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module (str, optional):\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\n    inject_request (bool, optional):\n        If ``True``, prepend ``request: Request`` to every handler so the\n        stub can later resolve services from ``request.app.state``.\n    package (bool, optional):\n        If ``True``, emit ``<resource>/routes.py`` packages (each with an\n        ``__init__.py``) instead of flat ``<resource>.py`` modules.\n    template_style (bool, optional):\n        If ``True``, emit ``async def`` handlers with a JSON body parameter\n        named ``body`` (the standards-template convention) plus a\n        service-resolution hint comment, instead of sync ``def`` handlers\n        taking ``payload``.\n\nReturns:\n    list[Path]:\n        Absolute paths of every generated route file.\n\nRaises:\n    OpenAPISpecLoadError:\n        If the spec cannot be loaded or validated.\n    ValueError:\n        If any operation is missing ``operationId``."
      }
    }
  }
}