fix: apply GSDFC docstring conformance, add minimal annotations to unannotated params (pydoclint zero); refresh lib/MCP docs

docs/lib/index.md

@@ -1,3 +1,4 @@
 # openapi_first
 
 ::: openapi_first
+- [Openapi First](openapi_first/)

docs/lib/openapi_first/app.md

@@ -0,0 +1,3 @@
+# App
+
+::: openapi_first.app

docs/lib/openapi_first/binder.md

@@ -0,0 +1,3 @@
+# Binder
+
+::: openapi_first.binder

docs/lib/openapi_first/cli.md

@@ -0,0 +1,3 @@
+# Cli
+
+::: openapi_first.cli

docs/lib/openapi_first/client.md

@@ -0,0 +1,3 @@
+# Client
+
+::: openapi_first.client

docs/lib/openapi_first/codegen.md

@@ -0,0 +1,3 @@
+# Codegen
+
+::: openapi_first.codegen

docs/lib/openapi_first/codegen_routes.md

@@ -0,0 +1,3 @@
+# Codegen Routes
+
+::: openapi_first.codegen_routes

docs/lib/openapi_first/errors.md

@@ -0,0 +1,3 @@
+# Errors
+
+::: openapi_first.errors

docs/lib/openapi_first/index.md

@@ -0,0 +1,13 @@
+# Openapi First
+
+::: openapi_first
+- [App](app.md)
+- [Binder](binder.md)
+- [Cli](cli.md)
+- [Client](client.md)
+- [Codegen](codegen.md)
+- [Codegen Routes](codegen_routes.md)
+- [Errors](errors.md)
+- [Loader](loader.md)
+- [Security](security.md)
+- [Templates](templates/)

docs/lib/openapi_first/loader.md

@@ -0,0 +1,3 @@
+# Loader
+
+::: openapi_first.loader

docs/lib/openapi_first/security.md

@@ -0,0 +1,3 @@
+# Security
+
+::: openapi_first.security

docs/lib/openapi_first/templates/crud_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.crud_app.data

docs/lib/openapi_first/templates/crud_app/index.md

@@ -0,0 +1,7 @@
+# Crud App
+
+::: openapi_first.templates.crud_app
+- [Data](data.md)
+- [Main](main.md)
+- [Routes](routes.md)
+- [Test Crud App](test_crud_app.md)

docs/lib/openapi_first/templates/crud_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.crud_app.main

docs/lib/openapi_first/templates/crud_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.crud_app.routes

docs/lib/openapi_first/templates/crud_app/test_crud_app.md

@@ -0,0 +1,3 @@
+# Test Crud App
+
+::: openapi_first.templates.crud_app.test_crud_app

docs/lib/openapi_first/templates/health_app/index.md

@@ -0,0 +1,5 @@
+# Health App
+
+::: openapi_first.templates.health_app
+- [Main](main.md)
+- [Routes](routes.md)

docs/lib/openapi_first/templates/health_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.health_app.main

docs/lib/openapi_first/templates/health_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.health_app.routes

docs/lib/openapi_first/templates/index.md

@@ -0,0 +1,7 @@
+# Templates
+
+::: openapi_first.templates
+- [Crud App](crud_app/)
+- [Health App](health_app/)
+- [Model App](model_app/)
+- [Vet App](vet_app/)

docs/lib/openapi_first/templates/model_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.model_app.data

docs/lib/openapi_first/templates/model_app/index.md

@@ -0,0 +1,8 @@
+# Model App
+
+::: openapi_first.templates.model_app
+- [Data](data.md)
+- [Main](main.md)
+- [Models](models.md)
+- [Routes](routes.md)
+- [Test Model App](test_model_app.md)

docs/lib/openapi_first/templates/model_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.model_app.main

docs/lib/openapi_first/templates/model_app/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: openapi_first.templates.model_app.models

docs/lib/openapi_first/templates/model_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.model_app.routes

docs/lib/openapi_first/templates/model_app/test_model_app.md

@@ -0,0 +1,3 @@
+# Test Model App
+
+::: openapi_first.templates.model_app.test_model_app

docs/lib/openapi_first/templates/vet_app/data.md

@@ -0,0 +1,3 @@
+# Data
+
+::: openapi_first.templates.vet_app.data

docs/lib/openapi_first/templates/vet_app/index.md

@@ -0,0 +1,9 @@
+# Vet App
+
+::: openapi_first.templates.vet_app
+- [Data](data.md)
+- [Main](main.md)
+- [Models](models.md)
+- [Routes](routes.md)
+- [Sse](sse.md)
+- [Test Vet App](test_vet_app.md)

docs/lib/openapi_first/templates/vet_app/main.md

@@ -0,0 +1,3 @@
+# Main
+
+::: openapi_first.templates.vet_app.main

docs/lib/openapi_first/templates/vet_app/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: openapi_first.templates.vet_app.models

docs/lib/openapi_first/templates/vet_app/routes.md

@@ -0,0 +1,3 @@
+# Routes
+
+::: openapi_first.templates.vet_app.routes

docs/lib/openapi_first/templates/vet_app/sse.md

@@ -0,0 +1,3 @@
+# Sse
+
+::: openapi_first.templates.vet_app.sse

docs/lib/openapi_first/templates/vet_app/test_vet_app.md

@@ -0,0 +1,3 @@
+# Test Vet App
+
+::: openapi_first.templates.vet_app.test_vet_app

docs/mcp/modules/openapi_first.app.json

@@ -18,6 +18,13 @@
         "signature": "<bound method Alias.signature of Alias('re', 're')>",
         "docstring": null
       },
+      "Any": {
+        "name": "Any",
+        "kind": "alias",
+        "path": "openapi_first.app.Any",
+        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+        "docstring": null
+      },
       "FastAPI": {
         "name": "FastAPI",
         "kind": "alias",
@@ -30,7 +37,7 @@
         "kind": "function",
         "path": "openapi_first.app.bind_routes",
         "signature": "<bound method Alias.signature of Alias('bind_routes', 'openapi_first.binder.bind_routes')>",
-        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (fastapi.FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (module):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (Any):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (Any):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
       },
       "load_openapi": {
         "name": "load_openapi",
@@ -57,7 +64,7 @@
         "name": "OpenAPIFirstApp",
         "kind": "class",
         "path": "openapi_first.app.OpenAPIFirstApp",
-        "signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 67, 150)>",
+        "signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 68, 151)>",
         "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
         "members": {
           "openapi": {
@@ -68,13 +75,6 @@
             "docstring": null
           }
         }
-      },
-      "Any": {
-        "name": "Any",
-        "kind": "alias",
-        "path": "openapi_first.app.Any",
-        "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
-        "docstring": null
       }
     }
   }

docs/mcp/modules/openapi_first.binder.json

@@ -30,7 +30,7 @@
         "kind": "function",
         "path": "openapi_first.binder.bind_routes",
         "signature": "<bound method Function.signature of Function('bind_routes', 42, 124)>",
-        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (fastapi.FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (module):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+        "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (Any):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (Any):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
       },
       "FastAPI": {
         "name": "FastAPI",

docs/mcp/modules/openapi_first.cli.json

@@ -2,7 +2,7 @@
   "module": "openapi_first.cli",
   "content": {
     "path": "openapi_first.cli",
-    "docstring": "Command-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\n---\n\n## Summary\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.",
+    "docstring": "# Summary\n\nCommand-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.",
     "objects": {
       "argparse": {
         "name": "argparse",
@@ -43,21 +43,21 @@
         "name": "available_templates",
         "kind": "function",
         "path": "openapi_first.cli.available_templates",
-        "signature": "<bound method Function.signature of Function('available_templates', 20, 33)>",
+        "signature": "<bound method Function.signature of Function('available_templates', 18, 31)>",
         "docstring": "Return a list of available application templates.\n\nReturns:\n    list[str]:\n        Sorted list of template names found in the internal templates directory."
       },
       "copy_template": {
         "name": "copy_template",
         "kind": "function",
         "path": "openapi_first.cli.copy_template",
-        "signature": "<bound method Function.signature of Function('copy_template', 36, 64)>",
+        "signature": "<bound method Function.signature of Function('copy_template', 34, 62)>",
         "docstring": "Copy a bundled OpenAPI-first application template into a directory.\n\nArgs:\n    template (str):\n        Name of the template to copy.\n    target_dir (Path):\n        Filesystem path where the template should be copied.\n\nRaises:\n    FileNotFoundError:\n        If the requested template does not exist."
       },
       "main": {
         "name": "main",
         "kind": "function",
         "path": "openapi_first.cli.main",
-        "signature": "<bound method Function.signature of Function('main', 67, 196)>",
+        "signature": "<bound method Function.signature of Function('main', 65, 194)>",
         "docstring": null
       }
     }

docs/mcp/modules/openapi_first.codegen.json

@@ -37,7 +37,7 @@
         "kind": "function",
         "path": "openapi_first.codegen.generate_routes",
         "signature": "<bound method Alias.signature of Alias('generate_routes', 'openapi_first.codegen_routes.generate_routes')>",
-        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n    spec_path:\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir:\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models:\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module:\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\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``."
+        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\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\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``."
       },
       "generate_models": {
         "name": "generate_models",

docs/mcp/modules/openapi_first.codegen_routes.json

@@ -2,7 +2,7 @@
   "module": "openapi_first.codegen_routes",
   "content": {
     "path": "openapi_first.codegen_routes",
-    "docstring": "Route 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.",
+    "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.",
     "objects": {
       "Path": {
         "name": "Path",
@@ -29,8 +29,8 @@
         "name": "generate_routes",
         "kind": "function",
         "path": "openapi_first.codegen_routes.generate_routes",
-        "signature": "<bound method Function.signature of Function('generate_routes', 27, 102)>",
-        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n    spec_path:\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir:\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models:\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module:\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\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``."
+        "signature": "<bound method Function.signature of Function('generate_routes', 29, 104)>",
+        "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\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\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``."
       }
     }
   }

docs/mcp/modules/openapi_first.json

@@ -25,6 +25,13 @@
             "signature": "<bound method Alias.signature of Alias('re', 're')>",
             "docstring": null
           },
+          "Any": {
+            "name": "Any",
+            "kind": "alias",
+            "path": "openapi_first.app.Any",
+            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
+            "docstring": null
+          },
           "FastAPI": {
             "name": "FastAPI",
             "kind": "alias",
@@ -37,7 +44,7 @@
             "kind": "function",
             "path": "openapi_first.app.bind_routes",
             "signature": "<bound method Alias.signature of Alias('bind_routes', 'openapi_first.binder.bind_routes')>",
-            "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (fastapi.FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (module):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+            "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (Any):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (Any):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
           },
           "load_openapi": {
             "name": "load_openapi",
@@ -64,7 +71,7 @@
             "name": "OpenAPIFirstApp",
             "kind": "class",
             "path": "openapi_first.app.OpenAPIFirstApp",
-            "signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 67, 150)>",
+            "signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 68, 151)>",
             "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n    **Responsibilities:**\n\n        - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n          registration with OpenAPI-driven binding.\n        - All routes are derived from the provided OpenAPI specification,\n          and each ``operationId`` is mapped to a Python function in the\n          supplied routes module.\n        - Auth dependencies are auto-injected from the spec's\n          ``securitySchemes`` and per-operation ``security`` fields.\n\n    **Guarantees:**\n\n        - No route can exist without an OpenAPI declaration.\n        - No OpenAPI operation can exist without a handler.\n        - Swagger UI and ``/openapi.json`` always reflect the provided spec.\n        - Handler functions remain framework-agnostic and testable.\n        - Auth enforcement is driven entirely by the spec — no manual\n          middleware or decorators required.\n\nExample:\n    ```python\n    from openapi_first import OpenAPIFirstApp\n    import app.routes as routes\n\n    app = OpenAPIFirstApp(\n        openapi_path=\"app/openapi.json\",\n        routes_module=routes,\n        title=\"Example Service\",\n    )\n    ```",
             "members": {
               "openapi": {
@@ -75,13 +82,6 @@
                 "docstring": null
               }
             }
-          },
-          "Any": {
-            "name": "Any",
-            "kind": "alias",
-            "path": "openapi_first.app.Any",
-            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
-            "docstring": null
           }
         }
       },
@@ -118,7 +118,7 @@
             "kind": "function",
             "path": "openapi_first.binder.bind_routes",
             "signature": "<bound method Function.signature of Function('bind_routes', 42, 124)>",
-            "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (fastapi.FastAPI):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (module):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
+            "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n    app (Any):\n        The FastAPI application instance to which routes will be added.\n    spec (dict):\n        Parsed OpenAPI 3.x specification dictionary.\n    routes_module (Any):\n        Python module containing handler functions. Each handler's name MUST\n        exactly match an OpenAPI `operationId`.\n    security_deps (dict[str, list[Any]] | None):\n        Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n        generated from the spec's ``securitySchemes`` and per-operation\n        ``security`` fields.\n\nRaises:\n    MissingOperationHandler:\n        If an ``operationId`` is missing from the spec or if no corresponding\n        handler function exists in the routes module.\n\nNotes:\n    **Responsibilities:**\n\n        - Iterates through the OpenAPI specification paths and methods.\n        - Resolves each ``operationId`` to a handler function, and registers\n          a corresponding ``APIRoute`` on the FastAPI application.\n        - Injects FastAPI ``Depends()`` for each security requirement found\n          on the operation or inherited from the top-level ``security`` field.\n\n    **Guarantees:**\n\n        - Route registration is deterministic and spec-driven. No route\n          decorators are required or supported. Handler resolution errors\n          surface at application startup."
           },
           "FastAPI": {
             "name": "FastAPI",
@@ -134,7 +134,7 @@
         "kind": "module",
         "path": "openapi_first.cli",
         "signature": null,
-        "docstring": "Command-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\n---\n\n## Summary\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.",
+        "docstring": "# Summary\n\nCommand-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.",
         "members": {
           "argparse": {
             "name": "argparse",
@@ -175,21 +175,21 @@
             "name": "available_templates",
             "kind": "function",
             "path": "openapi_first.cli.available_templates",
-            "signature": "<bound method Function.signature of Function('available_templates', 20, 33)>",
+            "signature": "<bound method Function.signature of Function('available_templates', 18, 31)>",
             "docstring": "Return a list of available application templates.\n\nReturns:\n    list[str]:\n        Sorted list of template names found in the internal templates directory."
           },
           "copy_template": {
             "name": "copy_template",
             "kind": "function",
             "path": "openapi_first.cli.copy_template",
-            "signature": "<bound method Function.signature of Function('copy_template', 36, 64)>",
+            "signature": "<bound method Function.signature of Function('copy_template', 34, 62)>",
             "docstring": "Copy a bundled OpenAPI-first application template into a directory.\n\nArgs:\n    template (str):\n        Name of the template to copy.\n    target_dir (Path):\n        Filesystem path where the template should be copied.\n\nRaises:\n    FileNotFoundError:\n        If the requested template does not exist."
           },
           "main": {
             "name": "main",
             "kind": "function",
             "path": "openapi_first.cli.main",
-            "signature": "<bound method Function.signature of Function('main', 67, 196)>",
+            "signature": "<bound method Function.signature of Function('main', 65, 194)>",
             "docstring": null
           }
         }
@@ -322,7 +322,7 @@
             "kind": "function",
             "path": "openapi_first.codegen.generate_routes",
             "signature": "<bound method Alias.signature of Alias('generate_routes', 'openapi_first.codegen_routes.generate_routes')>",
-            "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n    spec_path:\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir:\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models:\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module:\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\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``."
+            "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\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\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``."
           },
           "generate_models": {
             "name": "generate_models",
@@ -338,7 +338,7 @@
         "kind": "module",
         "path": "openapi_first.codegen_routes",
         "signature": null,
-        "docstring": "Route 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.",
+        "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.",
         "members": {
           "Path": {
             "name": "Path",
@@ -365,8 +365,8 @@
             "name": "generate_routes",
             "kind": "function",
             "path": "openapi_first.codegen_routes.generate_routes",
-            "signature": "<bound method Function.signature of Function('generate_routes', 27, 102)>",
-            "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n    spec_path:\n        Path to the OpenAPI specification file (YAML or JSON).\n    output_dir:\n        Directory where the generated route files are written.\n        Created automatically if it does not exist.\n    use_models:\n        If ``True``, import Pydantic models from *models_module*\n        for request-body schemas referenced via ``$ref``.\n    models_module:\n        Dotted Python module path from which to import models\n        (e.g. ``\"models\"``, ``\"app.models\"``).\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``."
+            "signature": "<bound method Function.signature of Function('generate_routes', 29, 104)>",
+            "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``<resource>.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\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\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``."
           }
         }
       },
@@ -463,7 +463,7 @@
         "kind": "module",
         "path": "openapi_first.security",
         "signature": null,
-        "docstring": "OpenAPI security scheme parsing and auto-generated auth dependencies.\n\nReads `securitySchemes` and per-operation `security` from an OpenAPI spec,\nresolves `{ENV_VAR}` placeholders in `x-` extension fields, and generates\nFastAPI dependencies for token validation (e.g., Bearer JWT introspection).",
+        "docstring": "# Summary\n\nOpenAPI security scheme parsing and auto-generated auth dependencies.\n\nThis module reads `securitySchemes` and per-operation `security` from an\nOpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields,\nand generates FastAPI dependencies for token validation (e.g., Bearer JWT\nintrospection).",
         "members": {
           "os": {
             "name": "os",
@@ -539,14 +539,14 @@
             "name": "parse_security_schemes",
             "kind": "function",
             "path": "openapi_first.security.parse_security_schemes",
-            "signature": "<bound method Function.signature of Function('parse_security_schemes', 43, 46)>",
+            "signature": "<bound method Function.signature of Function('parse_security_schemes', 46, 49)>",
             "docstring": "Extract and resolve environment variables in security schemes."
           },
           "make_security_dependencies": {
             "name": "make_security_dependencies",
             "kind": "function",
             "path": "openapi_first.security.make_security_dependencies",
-            "signature": "<bound method Function.signature of Function('make_security_dependencies', 113, 150)>",
+            "signature": "<bound method Function.signature of Function('make_security_dependencies', 116, 153)>",
             "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation."
           }
         }

docs/mcp/modules/openapi_first.security.json

@@ -2,7 +2,7 @@
   "module": "openapi_first.security",
   "content": {
     "path": "openapi_first.security",
-    "docstring": "OpenAPI security scheme parsing and auto-generated auth dependencies.\n\nReads `securitySchemes` and per-operation `security` from an OpenAPI spec,\nresolves `{ENV_VAR}` placeholders in `x-` extension fields, and generates\nFastAPI dependencies for token validation (e.g., Bearer JWT introspection).",
+    "docstring": "# Summary\n\nOpenAPI security scheme parsing and auto-generated auth dependencies.\n\nThis module reads `securitySchemes` and per-operation `security` from an\nOpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields,\nand generates FastAPI dependencies for token validation (e.g., Bearer JWT\nintrospection).",
     "objects": {
       "os": {
         "name": "os",
@@ -78,14 +78,14 @@
         "name": "parse_security_schemes",
         "kind": "function",
         "path": "openapi_first.security.parse_security_schemes",
-        "signature": "<bound method Function.signature of Function('parse_security_schemes', 43, 46)>",
+        "signature": "<bound method Function.signature of Function('parse_security_schemes', 46, 49)>",
         "docstring": "Extract and resolve environment variables in security schemes."
       },
       "make_security_dependencies": {
         "name": "make_security_dependencies",
         "kind": "function",
         "path": "openapi_first.security.make_security_dependencies",
-        "signature": "<bound method Function.signature of Function('make_security_dependencies', 113, 150)>",
+        "signature": "<bound method Function.signature of Function('make_security_dependencies', 116, 153)>",
         "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation."
       }
     }

docs/mcp/nav.json

@@ -1,130 +1,130 @@
 [
   {
     "module": "openapi_first",
-    "resource": "doc://modules/openapi_first"
+    "resource": "docs://modules/openapi_first"
   },
   {
     "module": "openapi_first.app",
-    "resource": "doc://modules/openapi_first.app"
+    "resource": "docs://modules/openapi_first.app"
   },
   {
     "module": "openapi_first.binder",
-    "resource": "doc://modules/openapi_first.binder"
+    "resource": "docs://modules/openapi_first.binder"
   },
   {
     "module": "openapi_first.cli",
-    "resource": "doc://modules/openapi_first.cli"
+    "resource": "docs://modules/openapi_first.cli"
   },
   {
     "module": "openapi_first.client",
-    "resource": "doc://modules/openapi_first.client"
+    "resource": "docs://modules/openapi_first.client"
   },
   {
     "module": "openapi_first.codegen",
-    "resource": "doc://modules/openapi_first.codegen"
+    "resource": "docs://modules/openapi_first.codegen"
   },
   {
     "module": "openapi_first.codegen_routes",
-    "resource": "doc://modules/openapi_first.codegen_routes"
+    "resource": "docs://modules/openapi_first.codegen_routes"
   },
   {
     "module": "openapi_first.errors",
-    "resource": "doc://modules/openapi_first.errors"
+    "resource": "docs://modules/openapi_first.errors"
   },
   {
     "module": "openapi_first.loader",
-    "resource": "doc://modules/openapi_first.loader"
+    "resource": "docs://modules/openapi_first.loader"
   },
   {
     "module": "openapi_first.security",
-    "resource": "doc://modules/openapi_first.security"
+    "resource": "docs://modules/openapi_first.security"
   },
   {
     "module": "openapi_first.templates",
-    "resource": "doc://modules/openapi_first.templates"
+    "resource": "docs://modules/openapi_first.templates"
   },
   {
     "module": "openapi_first.templates.crud_app",
-    "resource": "doc://modules/openapi_first.templates.crud_app"
+    "resource": "docs://modules/openapi_first.templates.crud_app"
   },
   {
     "module": "openapi_first.templates.crud_app.data",
-    "resource": "doc://modules/openapi_first.templates.crud_app.data"
+    "resource": "docs://modules/openapi_first.templates.crud_app.data"
   },
   {
     "module": "openapi_first.templates.crud_app.main",
-    "resource": "doc://modules/openapi_first.templates.crud_app.main"
+    "resource": "docs://modules/openapi_first.templates.crud_app.main"
   },
   {
     "module": "openapi_first.templates.crud_app.routes",
-    "resource": "doc://modules/openapi_first.templates.crud_app.routes"
+    "resource": "docs://modules/openapi_first.templates.crud_app.routes"
   },
   {
     "module": "openapi_first.templates.crud_app.test_crud_app",
-    "resource": "doc://modules/openapi_first.templates.crud_app.test_crud_app"
+    "resource": "docs://modules/openapi_first.templates.crud_app.test_crud_app"
   },
   {
     "module": "openapi_first.templates.health_app",
-    "resource": "doc://modules/openapi_first.templates.health_app"
+    "resource": "docs://modules/openapi_first.templates.health_app"
   },
   {
     "module": "openapi_first.templates.health_app.main",
-    "resource": "doc://modules/openapi_first.templates.health_app.main"
+    "resource": "docs://modules/openapi_first.templates.health_app.main"
   },
   {
     "module": "openapi_first.templates.health_app.routes",
-    "resource": "doc://modules/openapi_first.templates.health_app.routes"
+    "resource": "docs://modules/openapi_first.templates.health_app.routes"
   },
   {
     "module": "openapi_first.templates.model_app",
-    "resource": "doc://modules/openapi_first.templates.model_app"
+    "resource": "docs://modules/openapi_first.templates.model_app"
   },
   {
     "module": "openapi_first.templates.model_app.data",
-    "resource": "doc://modules/openapi_first.templates.model_app.data"
+    "resource": "docs://modules/openapi_first.templates.model_app.data"
   },
   {
     "module": "openapi_first.templates.model_app.main",
-    "resource": "doc://modules/openapi_first.templates.model_app.main"
+    "resource": "docs://modules/openapi_first.templates.model_app.main"
   },
   {
     "module": "openapi_first.templates.model_app.models",
-    "resource": "doc://modules/openapi_first.templates.model_app.models"
+    "resource": "docs://modules/openapi_first.templates.model_app.models"
   },
   {
     "module": "openapi_first.templates.model_app.routes",
-    "resource": "doc://modules/openapi_first.templates.model_app.routes"
+    "resource": "docs://modules/openapi_first.templates.model_app.routes"
   },
   {
     "module": "openapi_first.templates.model_app.test_model_app",
-    "resource": "doc://modules/openapi_first.templates.model_app.test_model_app"
+    "resource": "docs://modules/openapi_first.templates.model_app.test_model_app"
   },
   {
     "module": "openapi_first.templates.vet_app",
-    "resource": "doc://modules/openapi_first.templates.vet_app"
+    "resource": "docs://modules/openapi_first.templates.vet_app"
   },
   {
     "module": "openapi_first.templates.vet_app.data",
-    "resource": "doc://modules/openapi_first.templates.vet_app.data"
+    "resource": "docs://modules/openapi_first.templates.vet_app.data"
   },
   {
     "module": "openapi_first.templates.vet_app.main",
-    "resource": "doc://modules/openapi_first.templates.vet_app.main"
+    "resource": "docs://modules/openapi_first.templates.vet_app.main"
   },
   {
     "module": "openapi_first.templates.vet_app.models",
-    "resource": "doc://modules/openapi_first.templates.vet_app.models"
+    "resource": "docs://modules/openapi_first.templates.vet_app.models"
   },
   {
     "module": "openapi_first.templates.vet_app.routes",
-    "resource": "doc://modules/openapi_first.templates.vet_app.routes"
+    "resource": "docs://modules/openapi_first.templates.vet_app.routes"
   },
   {
     "module": "openapi_first.templates.vet_app.sse",
-    "resource": "doc://modules/openapi_first.templates.vet_app.sse"
+    "resource": "docs://modules/openapi_first.templates.vet_app.sse"
   },
   {
     "module": "openapi_first.templates.vet_app.test_vet_app",
-    "resource": "doc://modules/openapi_first.templates.vet_app.test_vet_app"
+    "resource": "docs://modules/openapi_first.templates.vet_app.test_vet_app"
   }
 ]